@drewpayment/mink 0.1.0

package/src/commands/init.ts

@@ -0,0 +1,159 @@
+import { execSync } from "child_process";
+import { mkdirSync, existsSync } from "fs";
+import { resolve, dirname, basename, join } from "path";
+import { projectDir, projectMetaPath } from "../core/paths";
+import { generateProjectId } from "../core/project-id";
+import { atomicWriteJson, safeReadJson } from "../core/fs-utils";
+
+interface HookCommand {
+  type: "command";
+  command: string;
+}
+
+interface HookEntry {
+  matcher: string;
+  hooks: HookCommand[];
+}
+
+type HooksConfig = Record<string, HookEntry[]>;
+
+export function detectRuntime(): "bun" | "node" {
+  try {
+    execSync("bun --version", { stdio: "ignore" });
+    return "bun";
+  } catch {
+    return "node";
+  }
+}
+
+export function buildHooksConfig(
+  runtime: "bun" | "node",
+  cliPath: string
+): HooksConfig {
+  const prefix = runtime === "bun" ? `bun run ${cliPath}` : `node ${cliPath}`;
+  const hook = (cmd: string): HookCommand[] => [{ type: "command", command: cmd }];
+  return {
+    SessionStart: [{ matcher: "", hooks: hook(`${prefix} session-start`) }],
+    Stop: [{ matcher: "", hooks: hook(`${prefix} session-stop`) }],
+    PreToolUse: [
+      { matcher: "Read", hooks: hook(`${prefix} pre-read`) },
+      { matcher: "Edit", hooks: hook(`${prefix} pre-write`) },
+      { matcher: "Write", hooks: hook(`${prefix} pre-write`) },
+    ],
+    PostToolUse: [
+      { matcher: "Read", hooks: hook(`${prefix} post-read`) },
+      { matcher: "Edit", hooks: hook(`${prefix} post-write`) },
+      { matcher: "Write", hooks: hook(`${prefix} post-write`) },
+    ],
+  };
+}
+
+function isMinkCommand(cmd: string): boolean {
+  return (
+    cmd.includes("cli") &&
+    (cmd.includes("session-start") ||
+      cmd.includes("session-stop") ||
+      cmd.includes("pre-read") ||
+      cmd.includes("post-read") ||
+      cmd.includes("pre-write") ||
+      cmd.includes("post-write"))
+  );
+}
+
+function isMinkHook(entry: HookEntry | Record<string, unknown>): boolean {
+  // Handle current format: { matcher, hooks: [{ type, command }] }
+  if (Array.isArray((entry as HookEntry).hooks)) {
+    return (entry as HookEntry).hooks.some((h) => isMinkCommand(h.command));
+  }
+  // Handle legacy format: { matcher, command }
+  if (typeof (entry as Record<string, unknown>).command === "string") {
+    return isMinkCommand((entry as Record<string, unknown>).command as string);
+  }
+  return false;
+}
+
+export function mergeHooksIntoSettings(
+  settingsPath: string,
+  newHooks: HooksConfig
+): void {
+  mkdirSync(dirname(settingsPath), { recursive: true });
+
+  const existing = (safeReadJson(settingsPath) as Record<string, unknown>) ?? {};
+  const existingHooks = (existing.hooks ?? {}) as HooksConfig;
+
+  // For each hook type mink manages, remove old mink entries then add new ones
+  for (const [event, entries] of Object.entries(newHooks)) {
+    const current = existingHooks[event] ?? [];
+    const withoutMink = current.filter((e) => !isMinkHook(e));
+    existingHooks[event] = [...withoutMink, ...entries];
+  }
+
+  existing.hooks = existingHooks;
+  atomicWriteJson(settingsPath, existing);
+}
+
+function isExistingInstallation(cwd: string): boolean {
+  const dir = projectDir(cwd);
+  if (!existsSync(dir)) return false;
+  return existsSync(join(dir, "file-index.json"));
+}
+
+export async function init(cwd: string): Promise<void> {
+  const runtime = detectRuntime();
+  const cliPath = resolve(dirname(new URL(import.meta.url).pathname), "../cli.ts");
+  const hooks = buildHooksConfig(runtime, cliPath);
+  const settingsPath = resolve(cwd, ".claude", "settings.json");
+  const dir = projectDir(cwd);
+  const upgrading = isExistingInstallation(cwd);
+
+  if (upgrading) {
+    console.log("[mink] existing installation detected, upgrading...");
+    const { createBackup } = await import("../core/backup");
+    const backupName = createBackup(cwd);
+    console.log(`  backup: ${backupName}`);
+  }
+
+  mergeHooksIntoSettings(settingsPath, hooks);
+
+  mkdirSync(dir, { recursive: true });
+
+  const projectId = generateProjectId(cwd);
+
+  // Write project metadata
+  const metaPath = projectMetaPath(cwd);
+  const existingMeta = safeReadJson(metaPath) as Record<string, unknown> | null;
+  atomicWriteJson(metaPath, {
+    ...(existingMeta ?? {}),
+    cwd,
+    name: basename(cwd),
+    initTimestamp: existingMeta?.initTimestamp ?? new Date().toISOString(),
+    version: "0.1.0",
+  });
+
+  if (upgrading) {
+    console.log(`[mink] upgrade complete`);
+    console.log(`  project:  ${projectId}`);
+    console.log(`  hooks:    ${settingsPath}`);
+  } else {
+    console.log(`[mink] initialized`);
+    console.log(`  project:  ${projectId}`);
+    console.log(`  state:    ${dir}`);
+    console.log(`  runtime:  ${runtime}`);
+    console.log(`  hooks:    ${settingsPath}`);
+  }
+
+  // Run initial scan
+  const { scan } = await import("./scan");
+  scan(cwd, { check: false });
+
+  // Seed learning memory if it doesn't exist
+  const { learningMemoryPath } = await import("../core/paths");
+  const memPath = learningMemoryPath(cwd);
+  if (!existsSync(memPath)) {
+    const { seedLearningMemory } = await import("../core/seed");
+    const { serializeLearningMemory } = await import("../core/learning-memory");
+    const { atomicWriteText } = await import("../core/fs-utils");
+    const mem = seedLearningMemory(cwd);
+    atomicWriteText(memPath, serializeLearningMemory(mem));
+  }
+}

package/src/commands/post-read.ts

@@ -0,0 +1,123 @@
+import { relative } from "path";
+import { readStdinJson } from "../core/stdin";
+import { sessionPath, fileIndexPath, actionLogPath } from "../core/paths";
+import { safeReadJson, atomicWriteJson } from "../core/fs-utils";
+import { createSessionState, isSessionState, recordRead } from "../core/session";
+import { isFileIndex, lookupEntry } from "../core/index-store";
+import { estimateTokens, isBinaryFile } from "../core/token-estimate";
+import { createActionLogWriter } from "../core/action-log";
+import type { SessionState } from "../types/session";
+import type { FileIndex } from "../types/file-index";
+import type { PostToolUseInput } from "../types/hook-input";
+
+export interface PostReadResult {
+  estimatedTokens: number;
+  indexHit: boolean;
+  source: "content" | "index-fallback" | "none";
+}
+
+export function analyzePostRead(
+  filePath: string,
+  content: string | null,
+  index: FileIndex | null
+): PostReadResult {
+  // Binary file — skip token estimation
+  if (isBinaryFile(filePath, content ?? undefined)) {
+    const entry = index ? lookupEntry(index, filePath) : null;
+    return { estimatedTokens: 0, indexHit: !!entry, source: "none" };
+  }
+
+  // Content available — estimate from actual content
+  if (content !== null && content.length > 0) {
+    const entry = index ? lookupEntry(index, filePath) : null;
+    return {
+      estimatedTokens: estimateTokens(content, filePath),
+      indexHit: !!entry,
+      source: "content",
+    };
+  }
+
+  // No content — try file index fallback
+  if (index) {
+    const entry = lookupEntry(index, filePath);
+    if (entry) {
+      return {
+        estimatedTokens: entry.estimatedTokens,
+        indexHit: true,
+        source: "index-fallback",
+      };
+    }
+  }
+
+  return { estimatedTokens: 0, indexHit: false, source: "none" };
+}
+
+function isPostToolUseInput(value: unknown): value is PostToolUseInput {
+  if (value === null || typeof value !== "object") return false;
+  const obj = value as Record<string, unknown>;
+  if (typeof obj.tool_name !== "string") return false;
+  if (typeof obj.tool_input !== "object" || obj.tool_input === null) return false;
+  return true;
+}
+
+function extractContent(input: PostToolUseInput): string | null {
+  if (!input.tool_output) return null;
+  if (typeof input.tool_output.content === "string") {
+    return input.tool_output.content;
+  }
+  return null;
+}
+
+export async function postRead(cwd: string): Promise<void> {
+  // 5-second safety timeout
+  const timer = setTimeout(() => process.exit(0), 5000);
+
+  try {
+    const input = await readStdinJson();
+    if (!isPostToolUseInput(input)) return;
+    if (input.tool_name !== "Read") return;
+
+    const absolutePath = input.tool_input.file_path;
+    if (!absolutePath) return;
+
+    const filePath = relative(cwd, absolutePath);
+
+    // Load session state (create fresh if missing)
+    const rawState = safeReadJson(sessionPath(cwd));
+    const state: SessionState = isSessionState(rawState)
+      ? rawState
+      : createSessionState();
+
+    // Load file index for token fallback and indexHit determination
+    const rawIndex = safeReadJson(fileIndexPath(cwd));
+    const index: FileIndex | null = isFileIndex(rawIndex) ? rawIndex : null;
+
+    // Extract content from tool output
+    const content = extractContent(input);
+
+    const result = analyzePostRead(filePath, content, index);
+
+    // Record the read in session state
+    recordRead(state, filePath, result.estimatedTokens, result.indexHit);
+
+    // Append read entry to action log
+    try {
+      const logWriter = createActionLogWriter(actionLogPath(cwd));
+      logWriter.appendReadEntry(
+        new Date().toISOString(),
+        filePath,
+        result.indexHit,
+        result.estimatedTokens
+      );
+    } catch {
+      // Never crash
+    }
+
+    // Persist state
+    atomicWriteJson(sessionPath(cwd), state);
+  } catch {
+    // Never crash — exit silently
+  } finally {
+    clearTimeout(timer);
+  }
+}

package/src/commands/post-write.ts

@@ -0,0 +1,157 @@
+import { relative } from "path";
+import { readFileSync } from "fs";
+import { readStdinJson } from "../core/stdin";
+import { sessionPath, fileIndexPath, actionLogPath } from "../core/paths";
+import { safeReadJson, atomicWriteJson } from "../core/fs-utils";
+import { createSessionState, isSessionState, recordWrite } from "../core/session";
+import {
+  isFileIndex,
+  lookupEntry,
+  upsertEntry,
+  createEmptyIndex,
+} from "../core/index-store";
+import { extractDescription } from "../core/description";
+import { estimateTokens, isBinaryFile } from "../core/token-estimate";
+import { isWriteExcluded } from "../core/write-exclusions";
+import { createActionLogWriter } from "../core/action-log";
+import type { SessionState } from "../types/session";
+import type { FileIndex, FileIndexEntry } from "../types/file-index";
+import type { PostToolUseInput } from "../types/hook-input";
+
+export interface PostWriteResult {
+  excluded: boolean;
+  action: "create" | "edit";
+  estimatedTokens: number;
+  description: string;
+  indexEntry: FileIndexEntry | null;
+}
+
+export function analyzePostWrite(
+  filePath: string,
+  fileContent: string | null,
+  index: FileIndex | null
+): PostWriteResult {
+  // Check exclusions
+  if (isWriteExcluded(filePath)) {
+    return {
+      excluded: true,
+      action: "edit",
+      estimatedTokens: 0,
+      description: "",
+      indexEntry: null,
+    };
+  }
+
+  // Determine action from index presence
+  const existingEntry = index ? lookupEntry(index, filePath) : null;
+  const action: "create" | "edit" = existingEntry ? "edit" : "create";
+
+  // Handle binary or unreadable content
+  if (fileContent === null || isBinaryFile(filePath, fileContent)) {
+    return {
+      excluded: false,
+      action,
+      estimatedTokens: 0,
+      description: "",
+      indexEntry: null,
+    };
+  }
+
+  // Extract description and estimate tokens
+  const description = extractDescription(filePath, fileContent);
+  const tokens = estimateTokens(fileContent, filePath);
+
+  // Build index entry
+  const now = new Date().toISOString();
+  const indexEntry: FileIndexEntry = {
+    filePath,
+    description,
+    estimatedTokens: tokens,
+    lastModified: now,
+    lastIndexed: now,
+  };
+
+  return {
+    excluded: false,
+    action,
+    estimatedTokens: tokens,
+    description,
+    indexEntry,
+  };
+}
+
+function isPostToolUseInput(value: unknown): value is PostToolUseInput {
+  if (value === null || typeof value !== "object") return false;
+  const obj = value as Record<string, unknown>;
+  if (typeof obj.tool_name !== "string") return false;
+  if (typeof obj.tool_input !== "object" || obj.tool_input === null) return false;
+  return true;
+}
+
+export async function postWrite(cwd: string): Promise<void> {
+  // 10-second safety timeout (longer due to file I/O + index updates)
+  const timer = setTimeout(() => process.exit(0), 10000);
+
+  try {
+    const input = await readStdinJson();
+    if (!isPostToolUseInput(input)) return;
+    if (input.tool_name !== "Write" && input.tool_name !== "Edit") return;
+
+    const absolutePath = input.tool_input.file_path;
+    if (!absolutePath) return;
+
+    const filePath = relative(cwd, absolutePath);
+
+    // Read file content from disk (post-write — file now exists)
+    let fileContent: string | null = null;
+    try {
+      fileContent = readFileSync(absolutePath, "utf-8");
+    } catch {
+      // File unreadable (permissions, race condition) — continue with null
+    }
+
+    // Load session state
+    const rawState = safeReadJson(sessionPath(cwd));
+    const state: SessionState = isSessionState(rawState)
+      ? rawState
+      : createSessionState();
+
+    // Load file index
+    const rawIndex = safeReadJson(fileIndexPath(cwd));
+    const index: FileIndex = isFileIndex(rawIndex) ? rawIndex : createEmptyIndex();
+
+    const result = analyzePostWrite(filePath, fileContent, index);
+
+    if (result.excluded) return;
+
+    // 1. File index update
+    if (result.indexEntry) {
+      upsertEntry(index, result.indexEntry);
+    }
+
+    // 2. Action log entry
+    try {
+      const logWriter = createActionLogWriter(actionLogPath(cwd));
+      logWriter.appendWriteEntry(
+        new Date().toISOString(),
+        filePath,
+        result.action,
+        result.description,
+        result.estimatedTokens
+      );
+    } catch {
+      // Never crash
+    }
+
+    // 3. Session state update
+    recordWrite(state, filePath, result.action, result.estimatedTokens);
+
+    // Persist state changes
+    atomicWriteJson(sessionPath(cwd), state);
+    atomicWriteJson(fileIndexPath(cwd), index);
+  } catch {
+    // Never crash — exit silently
+  } finally {
+    clearTimeout(timer);
+  }
+}

package/src/commands/pre-read.ts

@@ -0,0 +1,109 @@
+import { relative } from "path";
+import { readStdinJson } from "../core/stdin";
+import { sessionPath, fileIndexPath } from "../core/paths";
+import { safeReadJson, atomicWriteJson } from "../core/fs-utils";
+import { createSessionState, isSessionState } from "../core/session";
+import {
+  isFileIndex,
+  lookupEntry,
+  recordHit,
+  recordMiss,
+} from "../core/index-store";
+import type { SessionState } from "../types/session";
+import type { FileIndex, FileIndexEntry } from "../types/file-index";
+import type { PreToolUseInput } from "../types/hook-input";
+
+export interface PreReadResult {
+  warnings: string[];
+  indexHit: boolean;
+  repeatedRead: boolean;
+  entry: FileIndexEntry | null;
+}
+
+export function analyzePreRead(
+  filePath: string,
+  state: SessionState,
+  index: FileIndex | null
+): PreReadResult {
+  const warnings: string[] = [];
+  let repeatedRead = false;
+  let indexHit = false;
+  let entry: FileIndexEntry | null = null;
+
+  // Check for repeated read
+  const existing = state.reads[filePath];
+  if (existing) {
+    repeatedRead = true;
+    warnings.push(
+      `[mink] ${filePath} was already read this session (~${existing.estimatedTokens} tokens)`
+    );
+    state.counters.repeatedReadWarnings++;
+  }
+
+  // File index lookup
+  if (index) {
+    entry = lookupEntry(index, filePath);
+    if (entry) {
+      indexHit = true;
+      recordHit(index);
+      warnings.push(
+        `[mink] ${filePath} — ${entry.description} (~${entry.estimatedTokens} tokens)`
+      );
+    } else {
+      recordMiss(index);
+    }
+  }
+
+  return { warnings, indexHit, repeatedRead, entry };
+}
+
+function isPreToolUseInput(value: unknown): value is PreToolUseInput {
+  if (value === null || typeof value !== "object") return false;
+  const obj = value as Record<string, unknown>;
+  if (typeof obj.tool_name !== "string") return false;
+  if (typeof obj.tool_input !== "object" || obj.tool_input === null) return false;
+  return true;
+}
+
+export async function preRead(cwd: string): Promise<void> {
+  // 5-second safety timeout
+  const timer = setTimeout(() => process.exit(0), 5000);
+
+  try {
+    const input = await readStdinJson();
+    if (!isPreToolUseInput(input)) return;
+    if (input.tool_name !== "Read") return;
+
+    const absolutePath = input.tool_input.file_path;
+    if (!absolutePath) return;
+
+    const filePath = relative(cwd, absolutePath);
+
+    // Load session state (create fresh if missing)
+    const rawState = safeReadJson(sessionPath(cwd));
+    const state: SessionState = isSessionState(rawState)
+      ? rawState
+      : createSessionState();
+
+    // Load file index (null if missing/corrupt)
+    const rawIndex = safeReadJson(fileIndexPath(cwd));
+    const index: FileIndex | null = isFileIndex(rawIndex) ? rawIndex : null;
+
+    const result = analyzePreRead(filePath, state, index);
+
+    // Emit warnings to stderr
+    for (const warning of result.warnings) {
+      process.stderr.write(warning + "\n");
+    }
+
+    // Persist state changes
+    atomicWriteJson(sessionPath(cwd), state);
+    if (index) {
+      atomicWriteJson(fileIndexPath(cwd), index);
+    }
+  } catch {
+    // Never crash — exit silently
+  } finally {
+    clearTimeout(timer);
+  }
+}

package/src/commands/pre-write.ts

@@ -0,0 +1,136 @@
+import { relative } from "path";
+import { readFileSync } from "fs";
+import { readStdinJson } from "../core/stdin";
+import { sessionPath, learningMemoryPath, bugMemoryPath } from "../core/paths";
+import { safeReadJson, atomicWriteJson } from "../core/fs-utils";
+import { createSessionState, isSessionState } from "../core/session";
+import { parseLearningMemory, getEntries } from "../core/learning-memory";
+import { extractPatterns, matchPatterns } from "../core/pattern-engine";
+import {
+  loadBugMemory,
+  lookupBugsForFile,
+  formatBugSummary,
+} from "../core/bug-memory";
+import type { SessionState } from "../types/session";
+import type { PatternMatch } from "../types/learning-memory";
+import type { BugMemory } from "../types/bug-memory";
+import type { PreToolUseInput } from "../types/hook-input";
+
+export interface PreWriteResult {
+  warnings: string[];
+  patternMatches: PatternMatch[];
+  bugSummary: string | null;
+}
+
+export function analyzePreWrite(
+  filePath: string,
+  writeContent: string,
+  doNotRepeatEntries: string[],
+  bugMemory?: BugMemory
+): PreWriteResult {
+  const warnings: string[] = [];
+  const allMatches: PatternMatch[] = [];
+
+  // 1. Learning memory enforcement
+  if (doNotRepeatEntries.length > 0 && writeContent.length > 0) {
+    const patterns = extractPatterns(doNotRepeatEntries);
+    const matches = matchPatterns(patterns, writeContent);
+    allMatches.push(...matches);
+
+    for (const match of matches) {
+      warnings.push(
+        `[mink] Do-Not-Repeat violation: "${match.matchedText}" — from: ${match.pattern.sourceEntry}`
+      );
+    }
+  }
+
+  // 2. Bug memory lookup — surface known bugs for this file
+  let bugSummary: string | null = null;
+  if (bugMemory) {
+    const bugEntries = lookupBugsForFile(bugMemory, filePath);
+    bugSummary = formatBugSummary(bugEntries);
+  }
+
+  return { warnings, patternMatches: allMatches, bugSummary };
+}
+
+function isPreToolUseInput(value: unknown): value is PreToolUseInput {
+  if (value === null || typeof value !== "object") return false;
+  const obj = value as Record<string, unknown>;
+  if (typeof obj.tool_name !== "string") return false;
+  if (typeof obj.tool_input !== "object" || obj.tool_input === null) return false;
+  return true;
+}
+
+function extractWriteContent(input: PreToolUseInput): string {
+  const ti = input.tool_input;
+  if (input.tool_name === "Write" && typeof ti.content === "string") {
+    return ti.content;
+  }
+  if (input.tool_name === "Edit" && typeof ti.new_string === "string") {
+    return ti.new_string;
+  }
+  return "";
+}
+
+export async function preWrite(cwd: string): Promise<void> {
+  // 5-second safety timeout
+  const timer = setTimeout(() => process.exit(0), 5000);
+
+  try {
+    const input = await readStdinJson();
+    if (!isPreToolUseInput(input)) return;
+    if (input.tool_name !== "Write" && input.tool_name !== "Edit") return;
+
+    const absolutePath = input.tool_input.file_path;
+    if (!absolutePath) return;
+
+    const filePath = relative(cwd, absolutePath);
+    const writeContent = extractWriteContent(input);
+
+    // Load learning memory Do-Not-Repeat entries
+    let doNotRepeatEntries: string[] = [];
+    try {
+      const markdown = readFileSync(learningMemoryPath(cwd), "utf-8");
+      const mem = parseLearningMemory(markdown);
+      doNotRepeatEntries = getEntries(mem, "Do-Not-Repeat");
+    } catch {
+      // Learning memory not found or corrupt — skip enforcement
+    }
+
+    // Load bug memory for this file
+    let bugMemory: BugMemory | undefined;
+    try {
+      bugMemory = loadBugMemory(bugMemoryPath(cwd));
+    } catch {
+      // Bug memory not found or corrupt — skip lookup
+    }
+
+    const result = analyzePreWrite(filePath, writeContent, doNotRepeatEntries, bugMemory);
+
+    // Emit warnings to stderr (advisory only)
+    for (const warning of result.warnings) {
+      process.stderr.write(warning + "\n");
+    }
+
+    // Emit bug summary to stderr if there are known bugs for this file
+    if (result.bugSummary) {
+      process.stderr.write(result.bugSummary + "\n");
+    }
+
+    // Update session counters if there were pattern matches
+    if (result.patternMatches.length > 0) {
+      const rawState = safeReadJson(sessionPath(cwd));
+      const state: SessionState = isSessionState(rawState)
+        ? rawState
+        : createSessionState();
+
+      state.counters.learnedRuleWarnings += result.patternMatches.length;
+      atomicWriteJson(sessionPath(cwd), state);
+    }
+  } catch {
+    // Never crash — exit silently
+  } finally {
+    clearTimeout(timer);
+  }
+}