@drewpayment/mink 0.1.0

package/src/commands/reflect.ts

@@ -0,0 +1,39 @@
+import { existsSync, readFileSync } from "fs";
+import { parseLearningMemory, serializeLearningMemory } from "../core/learning-memory";
+import { reflectMemory } from "../core/reflection";
+import { atomicWriteText, safeReadJson } from "../core/fs-utils";
+import type { ReflectionResult } from "../types/learning-memory";
+import type { ProjectConfig } from "../types/file-index";
+
+const DEFAULT_TOKEN_BUDGET = 2000;
+
+export function reflect(
+  projectDir: string,
+  memoryPath: string,
+  configPath: string
+): ReflectionResult | null {
+  if (!existsSync(memoryPath)) {
+    console.log("[mink] no learning memory found");
+    return null;
+  }
+
+  const markdown = readFileSync(memoryPath, "utf-8");
+  const mem = parseLearningMemory(markdown);
+
+  const config = safeReadJson(configPath) as ProjectConfig | null;
+  const tokenBudget = config?.learningMemoryTokenBudget ?? DEFAULT_TOKEN_BUDGET;
+
+  const { memory: updated, result } = reflectMemory(mem, tokenBudget);
+
+  if (result.mergedCount > 0 || result.trimmedCount > 0) {
+    atomicWriteText(memoryPath, serializeLearningMemory(updated));
+  }
+
+  console.log(
+    `[mink] reflect: ${result.beforeTokens} → ${result.afterTokens} tokens` +
+      ` | merged: ${result.mergedCount} | trimmed: ${result.trimmedCount}` +
+      ` | within budget: ${result.withinBudget}`
+  );
+
+  return result;
+}

package/src/commands/restore.ts

@@ -0,0 +1,31 @@
+import { listBackups, restoreBackup } from "../core/backup";
+
+export function restore(cwd: string, args: string[]): void {
+  const backupName = args[0];
+
+  if (!backupName) {
+    // List available backups
+    const backups = listBackups(cwd);
+    if (backups.length === 0) {
+      console.log("[mink] no backups available");
+      return;
+    }
+
+    console.log("[mink] available backups:");
+    for (const b of backups) {
+      console.log(
+        `  ${b.name}  (${b.timestamp.toISOString().replace("T", " ").slice(0, 19)}, ${b.fileCount} files)`
+      );
+    }
+    return;
+  }
+
+  try {
+    restoreBackup(cwd, backupName);
+    console.log(`[mink] restored from: ${backupName}`);
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    console.error(`[mink] restore failed: ${msg}`);
+    process.exit(1);
+  }
+}

package/src/commands/scan.ts

@@ -0,0 +1,101 @@
+import { readFileSync } from "fs";
+import { join } from "path";
+import { fileIndexPath, configPath } from "../core/paths";
+import { atomicWriteJson, safeReadJson } from "../core/fs-utils";
+import { scanProject, loadConfig, getExcludes } from "../core/scanner";
+import { extractDescription } from "../core/description";
+import { estimateTokens } from "../core/token-estimate";
+import {
+  createEmptyIndex,
+  isFileIndex,
+  upsertEntry,
+  checkStaleness,
+} from "../core/index-store";
+import type { FileIndex, FileIndexEntry } from "../types/file-index";
+
+function loadExistingIndex(indexPath: string): FileIndex {
+  const raw = safeReadJson(indexPath);
+  if (isFileIndex(raw)) return raw;
+  if (raw !== null) {
+    console.error("[mink] file-index.json is corrupt — starting fresh");
+  }
+  return createEmptyIndex();
+}
+
+export function scan(cwd: string, options: { check: boolean }): void {
+  const idxPath = fileIndexPath(cwd);
+  const cfgPath = configPath(cwd);
+  const config = loadConfig(cfgPath);
+  const excludes = getExcludes(config);
+  const maxFiles = config.maxFiles ?? 500;
+
+  if (options.check) {
+    const existing = safeReadJson(idxPath);
+    if (!isFileIndex(existing)) {
+      console.error("[mink] no index found — run mink scan first");
+      process.exit(1);
+    }
+
+    const scanned = scanProject(cwd, excludes, maxFiles);
+    const scannedPaths = scanned.map((f) => f.relativePath);
+    const report = checkStaleness(existing, scannedPaths);
+
+    if (!report.isStale) {
+      console.log("[mink] index is up to date");
+      return;
+    }
+
+    if (report.missingFromIndex.length > 0) {
+      console.log(`Missing from index (${report.missingFromIndex.length}):`);
+      for (const f of report.missingFromIndex) {
+        console.log(`  + ${f}`);
+      }
+    }
+    if (report.orphanedEntries.length > 0) {
+      console.log(`Orphaned entries (${report.orphanedEntries.length}):`);
+      for (const f of report.orphanedEntries) {
+        console.log(`  - ${f}`);
+      }
+    }
+    process.exit(1);
+  }
+
+  // Full scan
+  const start = Date.now();
+  const index = loadExistingIndex(idxPath);
+
+  const scanned = scanProject(cwd, excludes, maxFiles);
+
+  // Build new entries, preserving lifetime counters
+  const newIndex = createEmptyIndex();
+  newIndex.header.lifetimeHits = index.header.lifetimeHits;
+  newIndex.header.lifetimeMisses = index.header.lifetimeMisses;
+
+  for (const file of scanned) {
+    const fullPath = join(cwd, file.relativePath);
+    let content: string;
+    try {
+      content = readFileSync(fullPath, "utf-8");
+    } catch {
+      continue; // Skip unreadable files
+    }
+
+    const entry: FileIndexEntry = {
+      filePath: file.relativePath,
+      description: extractDescription(file.relativePath, content),
+      estimatedTokens: estimateTokens(content, file.relativePath),
+      lastModified: new Date(file.mtimeMs).toISOString(),
+      lastIndexed: new Date().toISOString(),
+    };
+    upsertEntry(newIndex, entry);
+  }
+
+  newIndex.header.lastScanTimestamp = new Date().toISOString();
+
+  atomicWriteJson(idxPath, newIndex);
+
+  const elapsed = Date.now() - start;
+  console.log(
+    `[mink] indexed ${newIndex.header.totalFiles} files in ${elapsed}ms`
+  );
+}

package/src/commands/session-start.ts

@@ -0,0 +1,21 @@
+import { mkdirSync } from "fs";
+import { createSessionState } from "../core/session";
+import { projectDir, sessionPath, actionLogPath } from "../core/paths";
+import { atomicWriteJson } from "../core/fs-utils";
+import { createActionLogWriter } from "../core/action-log";
+
+export function sessionStart(cwd: string): void {
+  const dir = projectDir(cwd);
+  mkdirSync(dir, { recursive: true });
+
+  const state = createSessionState();
+  atomicWriteJson(sessionPath(cwd), state);
+
+  // Append session header to action log
+  try {
+    const logWriter = createActionLogWriter(actionLogPath(cwd));
+    logWriter.appendSessionHeader(state.startTimestamp);
+  } catch {
+    // Never crash hooks
+  }
+}

package/src/commands/session-stop.ts

@@ -0,0 +1,115 @@
+import { statSync, existsSync } from "fs";
+import { join, dirname } from "path";
+import { safeReadJson, atomicWriteJson } from "../core/fs-utils";
+import { isSessionState, buildSummary } from "../core/session";
+import { reflect } from "./reflect";
+import { createLedgerFinalizer } from "../core/token-ledger";
+import { loadBugMemory, hasBugForFileInSession } from "../core/bug-memory";
+import { createActionLogWriter, consolidateLog } from "../core/action-log";
+import type { SessionState, SessionFinalizer } from "../types/session";
+import type { ProjectConfig } from "../types/file-index";
+
+function hasActivity(state: SessionState): boolean {
+  return Object.keys(state.reads).length > 0 || state.writes.length > 0;
+}
+
+function getEditCounts(state: SessionState): Record<string, number> {
+  const counts: Record<string, number> = {};
+  for (const write of state.writes) {
+    counts[write.filePath] = (counts[write.filePath] || 0) + 1;
+  }
+  return counts;
+}
+
+function isLearningMemoryStale(memoryPath: string): boolean {
+  try {
+    const stat = statSync(memoryPath);
+    const ageMs = Date.now() - stat.mtimeMs;
+    const twentyFourHours = 24 * 60 * 60 * 1000;
+    return ageMs > twentyFourHours;
+  } catch {
+    // File doesn't exist yet — not stale, just absent
+    return false;
+  }
+}
+
+export function sessionStop(
+  sessionFile: string,
+  finalizer?: SessionFinalizer,
+  onReminder: (msg: string) => void = (msg) => console.error(msg)
+): void {
+  const raw = safeReadJson(sessionFile);
+  if (!isSessionState(raw)) {
+    if (raw !== null) {
+      console.error("[mink] session.json is corrupt — skipping finalization");
+    }
+    return;
+  }
+
+  const state: SessionState = raw;
+  state.stopCount++;
+
+  const projDir = dirname(sessionFile);
+  const effectiveFinalizer = finalizer ?? createLedgerFinalizer(projDir);
+
+  if (hasActivity(state)) {
+    const summary = buildSummary(state);
+
+    if (state.stopCount === 1) {
+      effectiveFinalizer.appendSession(summary);
+    } else {
+      effectiveFinalizer.updateSession(summary);
+    }
+
+    // Append session end to action log and run consolidation
+    try {
+      const logPath = join(projDir, "action-log.md");
+      const logWriter = createActionLogWriter(logPath);
+      logWriter.appendSessionEnd(summary);
+
+      const cfgRaw = safeReadJson(join(projDir, "config.json")) as ProjectConfig | null;
+      consolidateLog(logPath, {
+        maxEntries: cfgRaw?.actionLogMaxEntries ?? 200,
+        retentionDays: cfgRaw?.actionLogRetentionDays ?? 7,
+      });
+    } catch {
+      // Never crash
+    }
+  }
+
+  // Check for files edited 3+ times without a corresponding bug entry
+  const editCounts = getEditCounts(state);
+  const bugMemoryFile = join(projDir, "bug-memory.json");
+  const bugMemory = loadBugMemory(bugMemoryFile);
+
+  for (const [filePath, count] of Object.entries(editCounts)) {
+    if (count >= 3) {
+      const hasBug = hasBugForFileInSession(
+        bugMemory,
+        filePath,
+        state.startTimestamp
+      );
+      if (!hasBug) {
+        onReminder(
+          `[mink] ${filePath} was edited ${count} times — consider logging a bug`
+        );
+      }
+    }
+  }
+
+  // Run reflection to merge duplicates and prune oversized memory
+  const memoryPath = join(projDir, "learning-memory.md");
+  const cfgPath = join(projDir, "config.json");
+  if (existsSync(memoryPath)) {
+    reflect(projDir, memoryPath, cfgPath);
+  }
+
+  // Check if learning memory is stale (>24h since last update)
+  if (isLearningMemoryStale(memoryPath)) {
+    onReminder(
+      "[mink] learning memory hasn't been updated in 24+ hours — consider reviewing it"
+    );
+  }
+
+  atomicWriteJson(sessionFile, state);
+}

package/src/commands/status.ts

@@ -0,0 +1,152 @@
+import { existsSync, readFileSync, statSync } from "fs";
+import {
+  sessionPath,
+  fileIndexPath,
+  configPath,
+  learningMemoryPath,
+  tokenLedgerPath,
+  bugMemoryPath,
+  actionLogPath,
+} from "../core/paths";
+import { safeReadJson } from "../core/fs-utils";
+import { isFileIndex } from "../core/index-store";
+import { loadLedger } from "../core/token-ledger";
+import { parseLearningMemory, totalEntryCount } from "../core/learning-memory";
+import { loadBugMemory } from "../core/bug-memory";
+import { getDaemonStatus } from "../core/daemon";
+
+interface FileCheck {
+  name: string;
+  path: string;
+  status: "ok" | "missing" | "corrupt";
+}
+
+function checkJsonFile(name: string, filePath: string, validator?: (v: unknown) => boolean): FileCheck {
+  if (!existsSync(filePath)) return { name, path: filePath, status: "missing" };
+  const data = safeReadJson(filePath);
+  if (data === null) return { name, path: filePath, status: "corrupt" };
+  if (validator && !validator(data)) return { name, path: filePath, status: "corrupt" };
+  return { name, path: filePath, status: "ok" };
+}
+
+function checkTextFile(name: string, filePath: string): FileCheck {
+  if (!existsSync(filePath)) return { name, path: filePath, status: "missing" };
+  try {
+    readFileSync(filePath, "utf-8");
+    return { name, path: filePath, status: "ok" };
+  } catch {
+    return { name, path: filePath, status: "corrupt" };
+  }
+}
+
+export function status(cwd: string): void {
+  console.log("[mink] project status");
+  console.log();
+
+  // Section 1: State directory integrity
+  const checks: FileCheck[] = [
+    checkJsonFile("session.json", sessionPath(cwd)),
+    checkJsonFile("file-index.json", fileIndexPath(cwd), isFileIndex),
+    checkJsonFile("config.json", configPath(cwd)),
+    checkTextFile("learning-memory.md", learningMemoryPath(cwd)),
+    checkJsonFile("token-ledger.json", tokenLedgerPath(cwd)),
+    checkJsonFile("bug-memory.json", bugMemoryPath(cwd)),
+    checkTextFile("action-log.md", actionLogPath(cwd)),
+  ];
+
+  console.log("  State files:");
+  for (const check of checks) {
+    const icon = check.status === "ok" ? "ok" : check.status === "missing" ? "missing" : "corrupt";
+    console.log(`    ${check.name}: ${icon}`);
+  }
+
+  const corrupt = checks.filter((c) => c.status === "corrupt");
+  if (corrupt.length > 0) {
+    console.log();
+    console.log("  Warning: corrupted files detected. Consider running: mink restore");
+  }
+  console.log();
+
+  // Section 2: File index
+  try {
+    const raw = safeReadJson(fileIndexPath(cwd));
+    if (raw && isFileIndex(raw)) {
+      const h = raw.header;
+      const total = h.lifetimeHits + h.lifetimeMisses;
+      const ratio = total > 0 ? ((h.lifetimeHits / total) * 100).toFixed(1) : "N/A";
+      console.log("  File index:");
+      console.log(`    Files: ${h.totalFiles}`);
+      console.log(`    Last scan: ${h.lastScanTimestamp || "never"}`);
+      console.log(`    Hit/miss ratio: ${ratio}${total > 0 ? "%" : ""} (${h.lifetimeHits} hits, ${h.lifetimeMisses} misses)`);
+    } else {
+      console.log("  File index: not available");
+    }
+  } catch {
+    console.log("  File index: error reading");
+  }
+  console.log();
+
+  // Section 3: Token ledger
+  try {
+    const ledger = loadLedger(tokenLedgerPath(cwd));
+    const lt = ledger.lifetime;
+    console.log("  Token ledger:");
+    console.log(`    Sessions: ${lt.totalSessions}`);
+    console.log(`    Total tokens: ${lt.totalTokens.toLocaleString()}`);
+    console.log(`    Reads: ${lt.totalReads}  Writes: ${lt.totalWrites}`);
+    console.log(`    Estimated savings: ${lt.totalEstimatedSavings.toLocaleString()} tokens`);
+  } catch {
+    console.log("  Token ledger: error reading");
+  }
+  console.log();
+
+  // Section 4: Learning memory
+  try {
+    const memPath = learningMemoryPath(cwd);
+    if (existsSync(memPath)) {
+      const content = readFileSync(memPath, "utf-8");
+      const mem = parseLearningMemory(content);
+      const total = totalEntryCount(mem);
+      const mtime = statSync(memPath).mtime;
+      console.log("  Learning memory:");
+      console.log(`    User Preferences: ${mem.sections["User Preferences"].length}`);
+      console.log(`    Key Learnings: ${mem.sections["Key Learnings"].length}`);
+      console.log(`    Do-Not-Repeat: ${mem.sections["Do-Not-Repeat"].length}`);
+      console.log(`    Decision Log: ${mem.sections["Decision Log"].length}`);
+      console.log(`    Total entries: ${total}`);
+      console.log(`    Last modified: ${mtime.toISOString()}`);
+    } else {
+      console.log("  Learning memory: not initialized");
+    }
+  } catch {
+    console.log("  Learning memory: error reading");
+  }
+  console.log();
+
+  // Section 5: Bug log
+  try {
+    const bugs = loadBugMemory(bugMemoryPath(cwd));
+    console.log(`  Bug log: ${bugs.entries.length} entries`);
+  } catch {
+    console.log("  Bug log: error reading");
+  }
+  console.log();
+
+  // Section 6: Daemon status
+  try {
+    const daemon = getDaemonStatus(cwd);
+    if (daemon.running) {
+      const uptimeMs = Date.now() - new Date(daemon.startedAt!).getTime();
+      const uptimeMin = Math.floor(uptimeMs / 60_000);
+      const uptimeHrs = Math.floor(uptimeMin / 60);
+      const uptimeStr = uptimeHrs > 0
+        ? `${uptimeHrs}h ${uptimeMin % 60}m`
+        : `${uptimeMin}m`;
+      console.log(`  Daemon: running (PID: ${daemon.pid}, uptime: ${uptimeStr})`);
+    } else {
+      console.log("  Daemon: stopped");
+    }
+  } catch {
+    console.log("  Daemon: unknown");
+  }
+}

package/src/commands/update.ts

@@ -0,0 +1,121 @@
+import { resolve, dirname, basename } from "path";
+import { existsSync } from "fs";
+import { listRegisteredProjects } from "../core/project-registry";
+import { createBackup } from "../core/backup";
+import { projectMetaPath } from "../core/paths";
+import { atomicWriteJson, safeReadJson } from "../core/fs-utils";
+import { buildHooksConfig, detectRuntime, mergeHooksIntoSettings } from "./init";
+
+function parseArgs(args: string[]): {
+  dryRun: boolean;
+  project: string | null;
+  list: boolean;
+} {
+  let dryRun = false;
+  let project: string | null = null;
+  let list = false;
+
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === "--dry-run") dryRun = true;
+    else if (args[i] === "--list") list = true;
+    else if (args[i] === "--project" && i + 1 < args.length) {
+      project = args[++i];
+    }
+  }
+
+  return { dryRun, project, list };
+}
+
+export async function update(cwd: string, args: string[]): Promise<void> {
+  const { dryRun, project, list } = parseArgs(args);
+
+  const registered = listRegisteredProjects();
+
+  if (list) {
+    if (registered.length === 0) {
+      console.log("[mink] no registered projects found");
+      console.log("  Run 'mink init' in a project directory to register it.");
+      return;
+    }
+    console.log("[mink] registered projects:");
+    console.log(
+      "  " +
+        "ID".padEnd(30) +
+        "Name".padEnd(20) +
+        "Version".padEnd(12) +
+        "Path"
+    );
+    console.log("  " + "-".repeat(80));
+    for (const p of registered) {
+      console.log(
+        "  " +
+          p.id.padEnd(30) +
+          p.name.padEnd(20) +
+          p.version.padEnd(12) +
+          p.cwd
+      );
+    }
+    return;
+  }
+
+  let targets = registered;
+  if (project) {
+    targets = registered.filter(
+      (p) => p.name === project || p.id === project
+    );
+    if (targets.length === 0) {
+      console.error(`[mink] project not found: ${project}`);
+      console.error(
+        "  Available: " + registered.map((p) => p.name).join(", ")
+      );
+      process.exit(1);
+    }
+  }
+
+  if (targets.length === 0) {
+    console.log("[mink] no registered projects found");
+    console.log("  Run 'mink init' in a project directory to register it.");
+    return;
+  }
+
+  const runtime = detectRuntime();
+  const cliPath = resolve(
+    dirname(new URL(import.meta.url).pathname),
+    "../cli.ts"
+  );
+  const newHooks = buildHooksConfig(runtime, cliPath);
+
+  for (const target of targets) {
+    console.log(`[mink] updating: ${target.name} (${target.id})`);
+
+    if (dryRun) {
+      console.log("  [dry-run] would update hooks and project metadata");
+      console.log(`  [dry-run] would create backup before changes`);
+      continue;
+    }
+
+    // Create backup
+    const backupName = createBackup(target.cwd);
+    console.log(`  backup: ${backupName}`);
+
+    // Update hooks
+    const settingsPath = resolve(target.cwd, ".claude", "settings.json");
+    mergeHooksIntoSettings(settingsPath, newHooks);
+    console.log("  hooks: updated");
+
+    // Update project meta
+    const metaPath = projectMetaPath(target.cwd);
+    const existing = safeReadJson(metaPath) as Record<string, unknown> | null;
+    atomicWriteJson(metaPath, {
+      ...(existing ?? {}),
+      cwd: target.cwd,
+      name: target.name,
+      version: "0.1.0",
+    });
+    console.log("  metadata: updated");
+  }
+
+  if (!dryRun) {
+    console.log(`[mink] ${targets.length} project(s) updated`);
+  }
+}