@drewpayment/mink 0.1.0

package/src/core/token-ledger.ts

@@ -0,0 +1,185 @@
+import { join } from "path";
+import type { TokenLedger, LedgerSession, LifetimeCounters } from "../types/token-ledger";
+import type { SessionFinalizer, SessionSummary } from "../types/session";
+import { atomicWriteJson, safeReadJson } from "./fs-utils";
+
+// ── Helpers ──────────────────────────────────────────────────────────────────
+
+function addToLifetime(lifetime: LifetimeCounters, session: LedgerSession): void {
+  lifetime.totalTokens += session.totals.estimatedTokens;
+  lifetime.totalReads += session.totals.readCount;
+  lifetime.totalWrites += session.totals.writeCount;
+  lifetime.totalSessions += 1;
+  lifetime.totalFileIndexHits += session.totals.fileIndexHits;
+  lifetime.totalFileIndexMisses += session.totals.fileIndexMisses;
+  lifetime.totalRepeatedReads += session.totals.repeatedReads;
+  lifetime.totalEstimatedSavings += session.estimatedSavings;
+}
+
+function subtractFromLifetime(lifetime: LifetimeCounters, session: LedgerSession): void {
+  lifetime.totalTokens -= session.totals.estimatedTokens;
+  lifetime.totalReads -= session.totals.readCount;
+  lifetime.totalWrites -= session.totals.writeCount;
+  lifetime.totalSessions -= 1;
+  lifetime.totalFileIndexHits -= session.totals.fileIndexHits;
+  lifetime.totalFileIndexMisses -= session.totals.fileIndexMisses;
+  lifetime.totalRepeatedReads -= session.totals.repeatedReads;
+  lifetime.totalEstimatedSavings -= session.estimatedSavings;
+}
+
+// ── Core functions ────────────────────────────────────────────────────────────
+
+export function createEmptyLedger(): TokenLedger {
+  return {
+    lifetime: {
+      totalTokens: 0,
+      totalReads: 0,
+      totalWrites: 0,
+      totalSessions: 0,
+      totalFileIndexHits: 0,
+      totalFileIndexMisses: 0,
+      totalRepeatedReads: 0,
+      totalEstimatedSavings: 0,
+    },
+    sessions: [],
+  };
+}
+
+export function isTokenLedger(value: unknown): value is TokenLedger {
+  if (value === null || typeof value !== "object") return false;
+  const obj = value as Record<string, unknown>;
+  return (
+    typeof obj.lifetime === "object" &&
+    obj.lifetime !== null &&
+    Array.isArray(obj.sessions)
+  );
+}
+
+export function loadLedger(ledgerPath: string): TokenLedger {
+  const raw = safeReadJson(ledgerPath);
+  if (raw === null) {
+    return createEmptyLedger();
+  }
+  if (!isTokenLedger(raw)) {
+    console.warn(`[mink] Warning: corrupt token ledger at ${ledgerPath}, starting fresh`);
+    return createEmptyLedger();
+  }
+  return raw;
+}
+
+export function saveLedger(ledgerPath: string, ledger: TokenLedger): void {
+  atomicWriteJson(ledgerPath, ledger);
+}
+
+// ── Task 3: Append Session ────────────────────────────────────────────────────
+
+export function summaryToLedgerSession(summary: SessionSummary): LedgerSession {
+  return {
+    sessionId: summary.sessionId,
+    startTimestamp: summary.startTimestamp,
+    endTimestamp: summary.endTimestamp,
+    reads: summary.reads.map((r) => ({
+      filePath: r.filePath,
+      estimatedTokens: r.estimatedTokens,
+      readCount: r.readCount,
+    })),
+    writes: summary.writes.map((w) => ({
+      filePath: w.filePath,
+      estimatedTokens: w.estimatedTokens,
+      action: w.action,
+    })),
+    totals: {
+      readCount: summary.totals.readCount,
+      writeCount: summary.totals.writeCount,
+      estimatedTokens: summary.totals.estimatedTokens,
+      repeatedReads: summary.totals.repeatedReads,
+      fileIndexHits: summary.totals.fileIndexHits,
+      fileIndexMisses: summary.totals.fileIndexMisses,
+    },
+    estimatedSavings: summary.estimatedSavings,
+  };
+}
+
+export function appendSession(ledger: TokenLedger, summary: SessionSummary): void {
+  const session = summaryToLedgerSession(summary);
+  ledger.sessions.push(session);
+  addToLifetime(ledger.lifetime, session);
+}
+
+// ── Task 4: Update Session ────────────────────────────────────────────────────
+
+export function updateSession(ledger: TokenLedger, summary: SessionSummary): void {
+  const idx = ledger.sessions.findIndex((s) => s.sessionId === summary.sessionId);
+  if (idx === -1) {
+    appendSession(ledger, summary);
+    return;
+  }
+  const oldSession = ledger.sessions[idx];
+  subtractFromLifetime(ledger.lifetime, oldSession);
+  const newSession = summaryToLedgerSession(summary);
+  addToLifetime(ledger.lifetime, newSession);
+  ledger.sessions[idx] = newSession;
+}
+
+// ── Task 5: Archive ───────────────────────────────────────────────────────────
+
+export function archiveIfNeeded(
+  ledger: TokenLedger,
+  threshold: number = 1000
+): { archived: LedgerSession[] } {
+  if (threshold <= 0) {
+    return { archived: [] };
+  }
+  if (ledger.sessions.length <= threshold) {
+    return { archived: [] };
+  }
+  const excess = ledger.sessions.length - threshold;
+  const archived = ledger.sessions.splice(0, excess);
+  return { archived };
+}
+
+export function loadArchive(archivePath: string): LedgerSession[] {
+  const raw = safeReadJson(archivePath);
+  if (raw === null) {
+    return [];
+  }
+  if (!Array.isArray(raw)) {
+    console.warn(`[mink] Warning: corrupt token ledger archive at ${archivePath}, ignoring`);
+    return [];
+  }
+  return raw as LedgerSession[];
+}
+
+export function saveArchive(archivePath: string, newlyArchived: LedgerSession[]): void {
+  const existing = loadArchive(archivePath);
+  const combined = [...newlyArchived, ...existing];
+  atomicWriteJson(archivePath, combined);
+}
+
+// ── Task 6: Ledger Finalizer Factory ─────────────────────────────────────────
+
+export function createLedgerFinalizer(
+  projectDir: string,
+  archiveThreshold: number = 1000
+): SessionFinalizer {
+  const ledgerPath = join(projectDir, "token-ledger.json");
+  const archivePath = join(projectDir, "token-ledger-archive.json");
+
+  return {
+    appendSession(summary: SessionSummary): void {
+      const ledger = loadLedger(ledgerPath);
+      appendSession(ledger, summary);
+      const { archived } = archiveIfNeeded(ledger, archiveThreshold);
+      if (archived.length > 0) {
+        saveArchive(archivePath, archived);
+      }
+      saveLedger(ledgerPath, ledger);
+    },
+
+    updateSession(summary: SessionSummary): void {
+      const ledger = loadLedger(ledgerPath);
+      updateSession(ledger, summary);
+      saveLedger(ledgerPath, ledger);
+    },
+  };
+}

package/src/core/waste-detection.ts

@@ -0,0 +1,214 @@
+import type { WasteFlag, DetectionConfig } from "../types/waste-detection";
+import type { LedgerSession, TokenLedger } from "../types/token-ledger";
+import type { FileIndexEntry, FileIndexHeader } from "../types/file-index";
+import { estimateTokens } from "./token-estimate";
+
+// ── Default Config ──────────────────────────────────────────────────────────
+
+export function defaultDetectionConfig(): DetectionConfig {
+  return {
+    actionLogBloatThreshold: 5000,
+    learningMemoryStaleDays: 14,
+    indexMissRateThreshold: 0.20,
+    missedIndexMinTokens: 500,
+  };
+}
+
+// ── Detector 1: Repeated Reads ──────────────────────────────────────────────
+
+export function detectRepeatedReads(
+  sessions: LedgerSession[],
+  now: string
+): WasteFlag[] {
+  const flags: WasteFlag[] = [];
+
+  for (const session of sessions) {
+    for (const read of session.reads) {
+      if (read.readCount > 1) {
+        const wasted = (read.readCount - 1) * read.estimatedTokens;
+        flags.push({
+          pattern: "repeated-reads",
+          description: `File "${read.filePath}" was read ${read.readCount} times in session ${session.sessionId}`,
+          estimatedTokensWasted: wasted,
+          suggestion:
+            "Use the file index description instead of re-reading, or cache the content within the session.",
+          detectedAt: now,
+        });
+      }
+    }
+  }
+
+  return flags;
+}
+
+// ── Detector 2: Missed Index Opportunities ──────────────────────────────────
+
+export function detectMissedIndexOpportunities(
+  sessions: LedgerSession[],
+  indexEntries: Record<string, FileIndexEntry>,
+  config: DetectionConfig,
+  now: string
+): WasteFlag[] {
+  const aggregated = new Map<string, number>();
+
+  for (const session of sessions) {
+    for (const read of session.reads) {
+      if (read.estimatedTokens > config.missedIndexMinTokens) {
+        const entry = indexEntries[read.filePath];
+        if (entry && entry.description) {
+          const prev = aggregated.get(read.filePath) ?? 0;
+          aggregated.set(read.filePath, prev + read.estimatedTokens);
+        }
+      }
+    }
+  }
+
+  const flags: WasteFlag[] = [];
+  for (const [filePath, totalTokens] of aggregated) {
+    const entry = indexEntries[filePath];
+    flags.push({
+      pattern: "missed-index-opportunity",
+      description: `Read of "${filePath}" (~${totalTokens} tokens) could have used index description instead`,
+      estimatedTokensWasted: totalTokens,
+      suggestion: `Index description available: "${entry.description}". Consider using the index instead of full file reads.`,
+      detectedAt: now,
+    });
+  }
+
+  return flags;
+}
+
+// ── Detector 3: Action Log Bloat ────────────────────────────────────────────
+
+export function detectActionLogBloat(
+  actionLogContent: string,
+  config: DetectionConfig,
+  now: string
+): WasteFlag | null {
+  if (!actionLogContent) return null;
+
+  const tokenCount = estimateTokens(actionLogContent, "action-log.md");
+  if (tokenCount > config.actionLogBloatThreshold) {
+    return {
+      pattern: "action-log-bloat",
+      description: `Action log is ~${tokenCount} tokens, exceeding the ${config.actionLogBloatThreshold} token threshold`,
+      estimatedTokensWasted: tokenCount - config.actionLogBloatThreshold,
+      suggestion: "Run action log consolidation to reduce size.",
+      detectedAt: now,
+    };
+  }
+
+  return null;
+}
+
+// ── Detector 4: Learning Memory Staleness ───────────────────────────────────
+
+export function detectLearningMemoryStaleness(
+  lastModifiedMs: number | null,
+  config: DetectionConfig,
+  now: string
+): WasteFlag | null {
+  if (lastModifiedMs === null) {
+    return {
+      pattern: "learning-memory-staleness",
+      description: "Learning memory file is missing",
+      estimatedTokensWasted: 0,
+      suggestion:
+        "Create a learning memory file by running mink init, or manually create learning-memory.md.",
+      detectedAt: now,
+    };
+  }
+
+  const nowMs = Date.parse(now);
+  const ageMs = nowMs - lastModifiedMs;
+  const ageDays = ageMs / (1000 * 60 * 60 * 24);
+
+  if (ageDays > config.learningMemoryStaleDays) {
+    const lastUpdate = new Date(lastModifiedMs).toISOString().slice(0, 10);
+    return {
+      pattern: "learning-memory-staleness",
+      description: `Learning memory hasn't been updated in ${Math.floor(ageDays)} days (threshold: ${config.learningMemoryStaleDays} days)`,
+      estimatedTokensWasted: 0,
+      suggestion: "Review and update the learning memory to keep it current.",
+      detectedAt: now,
+    };
+  }
+
+  return null;
+}
+
+// ── Detector 5: Index Miss Rate ─────────────────────────────────────────────
+
+export function detectIndexMissRate(
+  lifetimeHits: number,
+  lifetimeMisses: number,
+  config: DetectionConfig,
+  now: string
+): WasteFlag | null {
+  const totalLookups = lifetimeHits + lifetimeMisses;
+  if (totalLookups === 0) return null;
+
+  const missRate = lifetimeMisses / totalLookups;
+  if (missRate > config.indexMissRateThreshold) {
+    const pct = Math.round(missRate * 100);
+    return {
+      pattern: "index-miss-rate",
+      description: `File index miss rate is ${pct}% (${lifetimeMisses} misses out of ${totalLookups} lookups)`,
+      estimatedTokensWasted: 0,
+      suggestion: "Run a full rescan with mink scan to update the file index.",
+      detectedAt: now,
+    };
+  }
+
+  return null;
+}
+
+// ── Orchestrator ────────────────────────────────────────────────────────────
+
+export function runDetection(
+  ledger: TokenLedger,
+  indexEntries: Record<string, FileIndexEntry>,
+  indexHeader: FileIndexHeader,
+  actionLogContent: string,
+  learningMemoryMtimeMs: number | null,
+  config?: Partial<DetectionConfig>,
+  now?: Date
+): WasteFlag[] {
+  const fullConfig: DetectionConfig = {
+    ...defaultDetectionConfig(),
+    ...config,
+  };
+  const nowStr = (now ?? new Date()).toISOString();
+
+  const flags: WasteFlag[] = [];
+
+  flags.push(...detectRepeatedReads(ledger.sessions, nowStr));
+  flags.push(
+    ...detectMissedIndexOpportunities(
+      ledger.sessions,
+      indexEntries,
+      fullConfig,
+      nowStr
+    )
+  );
+
+  const bloatFlag = detectActionLogBloat(actionLogContent, fullConfig, nowStr);
+  if (bloatFlag) flags.push(bloatFlag);
+
+  const stalenessFlag = detectLearningMemoryStaleness(
+    learningMemoryMtimeMs,
+    fullConfig,
+    nowStr
+  );
+  if (stalenessFlag) flags.push(stalenessFlag);
+
+  const missRateFlag = detectIndexMissRate(
+    indexHeader.lifetimeHits,
+    indexHeader.lifetimeMisses,
+    fullConfig,
+    nowStr
+  );
+  if (missRateFlag) flags.push(missRateFlag);
+
+  return flags;
+}

package/src/core/write-exclusions.ts

@@ -0,0 +1,24 @@
+import { basename } from "path";
+
+/**
+ * Returns true if the file should be excluded from write tracking.
+ * Excluded: .env* files, files inside the .mink state directory.
+ */
+export function isWriteExcluded(relativePath: string): boolean {
+  // Skip .mink state directory files
+  if (
+    relativePath === ".mink" ||
+    relativePath.startsWith(".mink/") ||
+    relativePath.startsWith(".mink\\")
+  ) {
+    return true;
+  }
+
+  // Skip .env files
+  const name = basename(relativePath);
+  if (name === ".env" || name.startsWith(".env.")) {
+    return true;
+  }
+
+  return false;
+}

package/src/types/action-log.ts

@@ -0,0 +1,20 @@
+export interface ActionLogEntry {
+  time: string; // HH:MM (UTC)
+  action: "Session start" | "Read" | "Create" | "Edit" | "Session end";
+  files: string; // Truncated file path or "—"
+  outcome: string; // index hit/miss, description, or summary
+  tokens: string; // "~NNN" or "—"
+}
+
+export interface ConsolidationConfig {
+  maxEntries: number; // default 200
+  retentionDays: number; // default 7
+}
+
+export interface ParsedSession {
+  startIndex: number; // char offset of session header
+  endIndex: number; // char offset of end of session (before next header or EOF)
+  date: string; // parsed date from session header (YYYY-MM-DD)
+  entryCount: number; // number of table data rows
+  content: string; // full text of this session block
+}

package/src/types/backup.ts

@@ -0,0 +1,6 @@
+export interface BackupInfo {
+  name: string;
+  timestamp: Date;
+  path: string;
+  fileCount: number;
+}

package/src/types/bug-memory.ts

@@ -0,0 +1,24 @@
+export interface BugEntry {
+  id: string;
+  createdAt: string;
+  lastSeenAt: string;
+  errorMessage: string;
+  filePath: string;
+  lineNumber?: number;
+  rootCause: string;
+  fixDescription: string;
+  tags: string[];
+  occurrenceCount: number;
+  relatedBugIds: string[];
+}
+
+export interface BugMemory {
+  entries: BugEntry[];
+  nextId: number;
+}
+
+export interface SimilarityMatch {
+  entry: BugEntry;
+  score: number;
+  matchReasons: string[];
+}

package/src/types/config.ts

@@ -0,0 +1,59 @@
+export interface GlobalConfig {
+  "wiki.path"?: string;
+  "wiki.enabled"?: string;
+  "wiki.sync-mode"?: string;
+  "wiki.git-backup"?: string;
+  "wiki.git-remote"?: string;
+}
+
+export type ConfigKey = keyof GlobalConfig & string;
+
+export interface ConfigKeyMeta {
+  key: ConfigKey;
+  default: string;
+  envVar: string;
+  description: string;
+}
+
+export const CONFIG_KEYS: ConfigKeyMeta[] = [
+  {
+    key: "wiki.path",
+    default: "~/.mink/wiki/",
+    envVar: "MINK_WIKI_PATH",
+    description: "Wiki vault location",
+  },
+  {
+    key: "wiki.enabled",
+    default: "true",
+    envVar: "MINK_WIKI_ENABLED",
+    description: "Enable/disable the wiki feature",
+  },
+  {
+    key: "wiki.sync-mode",
+    default: "immediate",
+    envVar: "MINK_WIKI_SYNC_MODE",
+    description: "Sync mode: immediate or batched",
+  },
+  {
+    key: "wiki.git-backup",
+    default: "false",
+    envVar: "MINK_WIKI_GIT_BACKUP",
+    description: "Enable/disable auto-commit and push",
+  },
+  {
+    key: "wiki.git-remote",
+    default: "origin",
+    envVar: "MINK_WIKI_GIT_REMOTE",
+    description: "Git remote name for push",
+  },
+];
+
+const VALID_KEYS = new Set<string>(CONFIG_KEYS.map((k) => k.key));
+
+export function isValidConfigKey(key: string): key is ConfigKey {
+  return VALID_KEYS.has(key);
+}
+
+export function getConfigKeyMeta(key: ConfigKey): ConfigKeyMeta {
+  return CONFIG_KEYS.find((k) => k.key === key)!;
+}

package/src/types/dashboard.ts

@@ -0,0 +1,104 @@
+import type { LifetimeCounters, LedgerSession } from "./token-ledger";
+import type { WasteFlag } from "./waste-detection";
+import type { FileIndexHeader, FileIndexEntry } from "./file-index";
+import type { BugEntry } from "./bug-memory";
+import type { LearningMemory } from "./learning-memory";
+import type { ParsedSession } from "./action-log";
+import type { TaskDefinition, TaskRunRecord, DeadLetterEntry } from "./scheduler";
+
+// ── State File Identifiers ─────────────────────────────────────────────────
+
+export type StateFileId =
+  | "token-ledger"
+  | "file-index"
+  | "learning-memory"
+  | "bug-memory"
+  | "action-log"
+  | "scheduler-manifest"
+  | "session"
+  | "project-meta"
+  | "design-report"
+  | "project-switched";
+
+// ── SSE Event ──────────────────────────────────────────────────────────────
+
+export interface StateChangeEvent {
+  fileId: StateFileId;
+  projectId?: string;
+  timestamp: string;
+}
+
+// ── File Status ────────────────────────────────────────────────────────────
+
+export interface FileStatus {
+  name: string;
+  status: "ok" | "missing" | "corrupt";
+}
+
+// ── API Payloads ───────────────────────────────────────────────────────────
+
+export interface OverviewPayload {
+  project: { name: string; description: string; cwd: string } | null;
+  daemon: {
+    running: boolean;
+    pid?: number;
+    startedAt?: string;
+    uptimeMs?: number;
+  };
+  summary: {
+    totalSessions: number;
+    totalTokens: number;
+    totalReads: number;
+    totalWrites: number;
+    estimatedSavings: number;
+  };
+  stateFiles: FileStatus[];
+}
+
+export interface TokenLedgerPayload {
+  lifetime: LifetimeCounters;
+  sessions: LedgerSession[];
+  wasteFlags: WasteFlag[];
+}
+
+export interface FileIndexPayload {
+  header: FileIndexHeader;
+  entries: FileIndexEntry[];
+}
+
+export interface SchedulerTaskPayload {
+  definition: TaskDefinition;
+  state: TaskRunRecord | null;
+}
+
+export interface SchedulerPayload {
+  tasks: SchedulerTaskPayload[];
+  deadLetterQueue: DeadLetterEntry[];
+  lastHeartbeat: string | null;
+}
+
+export interface BugLogPayload {
+  entries: BugEntry[];
+  nextId: number;
+}
+
+export interface ActionLogPayload {
+  sessions: ParsedSession[];
+}
+
+export interface ActionResult {
+  success: boolean;
+  error?: string;
+}
+
+export interface DesignImagePayload {
+  url: string;
+  route: string;
+  viewport: string;
+  section: number;
+  timestamp: string;
+}
+
+export interface DesignPayload {
+  images: DesignImagePayload[];
+}