@drewpayment/mink 0.8.0 → 0.9.1

package/src/core/note-writer.ts

@@ -1,10 +1,55 @@
 import { join } from "path";
 import { existsSync, readFileSync } from "fs";
-import { atomicWriteText } from "./fs-utils";
+import { createHash } from "crypto";
+import { atomicWriteText, safeAppendText } from "./fs-utils";
 import { categoryToDir, vaultDailyDir, vaultTemplates } from "./vault";
 import { loadTemplate } from "./vault-templates";
+import { getOrCreateDeviceId } from "./device";
 import type { NoteMetadata, NoteFrontmatter, NoteCategory } from "../types/note";
 
+const MAX_COLLISION_ATTEMPTS = 4;
+
+function sha256(content: string): string {
+  return createHash("sha256").update(content).digest("hex");
+}
+
+// Resolve the target path for a note write so two devices creating notes with
+// the same slug never overwrite each other. Strategy:
+//   1. If the path is free, use it as-is.
+//   2. If the path holds the exact same content (idempotent re-save), reuse
+//      the path so the write is a no-op.
+//   3. Otherwise append a short device suffix and retry. Fall back to a
+//      timestamp suffix if the device suffix is also taken.
+function resolveUniqueNotePath(
+  dir: string,
+  baseSlug: string,
+  content: string
+): string {
+  const targetHash = sha256(content);
+  const primary = join(dir, `${baseSlug}.md`);
+  if (!existsSync(primary)) return primary;
+  if (sameContent(primary, targetHash)) return primary;
+
+  const dev4 = getOrCreateDeviceId().replace(/-/g, "").slice(0, 4);
+  for (let i = 0; i < MAX_COLLISION_ATTEMPTS; i++) {
+    const suffix = i === 0 ? dev4 : `${dev4}-${i + 1}`;
+    const candidate = join(dir, `${baseSlug}-${suffix}.md`);
+    if (!existsSync(candidate)) return candidate;
+    if (sameContent(candidate, targetHash)) return candidate;
+  }
+
+  // Final fallback: timestamp suffix (effectively guaranteed unique).
+  return join(dir, `${baseSlug}-${Date.now()}.md`);
+}
+
+function sameContent(filePath: string, expectedHash: string): boolean {
+  try {
+    return sha256(readFileSync(filePath, "utf-8")) === expectedHash;
+  } catch {
+    return false;
+  }
+}
+
 export function slugifyTitle(title: string): string {
   return title
     .toLowerCase()
@@ -61,7 +106,6 @@ export function createNote(meta: NoteMetadata): {
   const now = meta.created || new Date().toISOString();
   const slug = slugifyTitle(meta.title);
   const dir = categoryToDir(meta.category, meta.projectSlug);
-  const filePath = join(dir, `${slug}.md`);
 
   let content: string;
 
@@ -78,6 +122,7 @@ export function createNote(meta: NoteMetadata): {
     content = buildNoteContent(meta, now);
   }
 
+  const filePath = resolveUniqueNotePath(dir, slug, content);
   atomicWriteText(filePath, content);
   return { filePath, content };
 }
@@ -104,14 +149,15 @@ export function appendToDaily(date: string, content: string): string {
   const filePath = join(dir, `${date}.md`);
 
   if (existsSync(filePath)) {
-    const existing = readFileSync(filePath, "utf-8");
+    // Append-only so `merge=union` cleanly resolves cross-device daily entries
+    // — full-file rewrites would defeat union merging and reintroduce conflict
+    // markers when two devices append on the same day.
     const timestamp = new Date().toLocaleTimeString("en-US", {
       hour: "2-digit",
       minute: "2-digit",
       hour12: false,
     });
-    const updated = `${existing.trimEnd()}\n\n## ${timestamp}\n\n${content}\n`;
-    atomicWriteText(filePath, updated);
+    safeAppendText(filePath, `\n\n## ${timestamp}\n\n${content}\n`);
   } else {
     const now = new Date().toISOString();
     const rendered = loadTemplate(vaultTemplates(), "daily-note", {
@@ -197,7 +243,7 @@ export function ingestFile(
 
   const slug = slugifyTitle(title);
   const dir = categoryToDir(meta.category, meta.projectSlug);
-  const filePath = join(dir, `${slug}.md`);
+  const filePath = resolveUniqueNotePath(dir, slug, content);
   atomicWriteText(filePath, content);
   return { filePath, content };
 }

package/src/core/paths.ts

@@ -2,15 +2,26 @@ import { join } from "path";
 import { homedir } from "os";
 import { generateProjectId } from "./project-id";
 
-const MINK_ROOT = join(homedir(), ".mink");
+// Resolved per-call so tests can override via MINK_ROOT_OVERRIDE without
+// reloading modules. Production callers get the default homedir/.mink path.
+function resolveMinkRoot(): string {
+  return process.env.MINK_ROOT_OVERRIDE || join(homedir(), ".mink");
+}
+
+const MINK_ROOT = resolveMinkRoot();
 
 export function minkRoot(): string {
+  // Re-resolve when the test override is in play so individual tests can
+  // point at their own temp dir without contaminating each other.
+  if (process.env.MINK_ROOT_OVERRIDE) {
+    return process.env.MINK_ROOT_OVERRIDE;
+  }
   return MINK_ROOT;
 }
 
 export function projectDir(cwd: string): string {
   const id = generateProjectId(cwd);
-  return join(MINK_ROOT, "projects", id);
+  return join(minkRoot(), "projects", id);
 }
 
 export function sessionPath(cwd: string): string {
@@ -46,11 +57,11 @@ export function actionLogPath(cwd: string): string {
 }
 
 export function schedulerPidPath(): string {
-  return join(MINK_ROOT, "scheduler.pid");
+  return join(minkRoot(), "scheduler.pid");
 }
 
 export function schedulerLogPath(): string {
-  return join(MINK_ROOT, "scheduler.log");
+  return join(minkRoot(), "scheduler.log");
 }
 
 export function schedulerManifestPath(cwd: string): string {
@@ -58,27 +69,27 @@ export function schedulerManifestPath(cwd: string): string {
 }
 
 export function channelPidPath(): string {
-  return join(MINK_ROOT, "channel.pid");
+  return join(minkRoot(), "channel.pid");
 }
 
 export function channelLogPath(): string {
-  return join(MINK_ROOT, "channel.log");
+  return join(minkRoot(), "channel.log");
 }
 
 export function globalConfigPath(): string {
-  return join(MINK_ROOT, "config");
+  return join(minkRoot(), "config");
 }
 
 export function localConfigPath(): string {
-  return join(MINK_ROOT, "config.local");
+  return join(minkRoot(), "config.local");
 }
 
 export function deviceIdPath(): string {
-  return join(MINK_ROOT, "device-id");
+  return join(minkRoot(), "device-id");
 }
 
 export function deviceRegistryPath(): string {
-  return join(MINK_ROOT, "devices.json");
+  return join(minkRoot(), "devices.json");
 }
 
 export function projectMetaPath(cwd: string): string {
@@ -89,6 +100,51 @@ export function backupDirPath(cwd: string): string {
   return join(projectDir(cwd), "backups");
 }
 
+// ── Sync v2 — shard-aware paths ────────────────────────────────────────────
+// Per-device shards isolate machine-rewritten state files so two devices never
+// write to the same path. Aggregators in state-aggregator.ts compose the
+// authoritative view by reading every device's shard plus the legacy paths
+// above. The legacy helpers (tokenLedgerPath, bugMemoryPath, actionLogPath,
+// tokenLedgerArchivePath) remain valid for fallback reads during the migration
+// window — they are NOT removed.
+
+export function syncVersionPath(): string {
+  return join(minkRoot(), ".mink-sync-version");
+}
+
+export function projectStateDir(cwd: string): string {
+  return join(projectDir(cwd), "state");
+}
+
+export function deviceShardDir(cwd: string, deviceId: string): string {
+  return join(projectStateDir(cwd), deviceId);
+}
+
+export function tokenLedgerShardPath(cwd: string, deviceId: string): string {
+  return join(deviceShardDir(cwd, deviceId), "token-ledger.json");
+}
+
+export function tokenLedgerArchiveShardPath(cwd: string, deviceId: string): string {
+  return join(deviceShardDir(cwd, deviceId), "token-ledger-archive.json");
+}
+
+export function bugMemoryShardPath(cwd: string, deviceId: string): string {
+  return join(deviceShardDir(cwd, deviceId), "bug-memory.json");
+}
+
+export function actionLogShardPath(cwd: string, deviceId: string): string {
+  return join(deviceShardDir(cwd, deviceId), "action-log.md");
+}
+
+export function learningMemorySidecarPath(cwd: string, deviceId: string): string {
+  return join(projectDir(cwd), `learning-memory.${deviceId}.md`);
+}
+
+// Per-device telemetry counters split out of file-index.json (gitignored, not synced).
+export function fileIndexCountersPath(cwd: string): string {
+  return join(projectDir(cwd), ".mink-state-counters.json");
+}
+
 export function designCapturesDir(cwd: string): string {
   return join(projectDir(cwd), "design-captures");
 }

package/src/core/state-aggregator.ts

@@ -0,0 +1,304 @@
+import { existsSync, readdirSync, readFileSync, statSync } from "fs";
+import { join } from "path";
+import { projectDir } from "./paths";
+import {
+  loadLedger,
+  loadArchive,
+  createEmptyLedger,
+} from "./token-ledger";
+import { loadBugMemory, createEmptyBugMemory } from "./bug-memory";
+import {
+  parseLearningMemory,
+  createEmptyLearningMemory,
+} from "./learning-memory";
+import { parseLogSessions, safeReadLog } from "./action-log";
+import type {
+  TokenLedger,
+  LedgerSession,
+  LifetimeCounters,
+} from "../types/token-ledger";
+import type { BugMemory, BugEntry } from "../types/bug-memory";
+import type {
+  LearningMemory,
+  SectionName,
+} from "../types/learning-memory";
+
+// ── Shard discovery ────────────────────────────────────────────────────────
+// All aggregators take a project state directory (the path returned by
+// projectDir(cwd)). The cwd-based variants below are thin wrappers for the
+// common case where the caller has cwd in hand.
+
+function listDeviceShardsAt(projDir: string): string[] {
+  const stateDir = join(projDir, "state");
+  if (!existsSync(stateDir)) return [];
+  try {
+    return readdirSync(stateDir).filter((name) => {
+      try {
+        return statSync(join(stateDir, name)).isDirectory();
+      } catch {
+        return false;
+      }
+    });
+  } catch {
+    return [];
+  }
+}
+
+const SIDECAR_RE = /^learning-memory\.([^.]+)\.md$/;
+
+function listLearningMemorySidecarPathsAt(projDir: string): string[] {
+  if (!existsSync(projDir)) return [];
+  try {
+    return readdirSync(projDir)
+      .filter((f) => SIDECAR_RE.test(f))
+      .map((f) => join(projDir, f));
+  } catch {
+    return [];
+  }
+}
+
+function shardPath(projDir: string, deviceId: string, file: string): string {
+  return join(projDir, "state", deviceId, file);
+}
+
+// ── Token ledger ───────────────────────────────────────────────────────────
+
+function addLifetime(target: LifetimeCounters, source: LifetimeCounters): void {
+  target.totalTokens += source.totalTokens;
+  target.totalReads += source.totalReads;
+  target.totalWrites += source.totalWrites;
+  target.totalSessions += source.totalSessions;
+  target.totalFileIndexHits += source.totalFileIndexHits;
+  target.totalFileIndexMisses += source.totalFileIndexMisses;
+  target.totalRepeatedReads += source.totalRepeatedReads;
+  target.totalEstimatedSavings += source.totalEstimatedSavings;
+}
+
+export function aggregateTokenLedgerAt(projDir: string): TokenLedger {
+  const merged = createEmptyLedger();
+  const seenSessions = new Set<string>();
+
+  // Sum lifetime counters from every source (each shard + legacy). Lifetime
+  // persists across archive cycles, so deriving from active sessions alone
+  // would lose archived totals. Migration atomically moves legacy → shard
+  // (`git mv`), so a session never lives in both simultaneously and lifetime
+  // counters do not double-count in production.
+  const sources = [
+    ...listDeviceShardsAt(projDir).map((id) =>
+      shardPath(projDir, id, "token-ledger.json")
+    ),
+    join(projDir, "token-ledger.json"),
+  ];
+
+  // Track waste-flags across sources, deduped by (pattern, detectedAt) so
+  // each device's flags remain visible without spamming duplicates.
+  const seenFlagKeys = new Set<string>();
+  const wasteFlags: NonNullable<TokenLedger["wasteFlags"]> = [];
+
+  for (const path of sources) {
+    if (!existsSync(path)) continue;
+    const ledger = loadLedger(path);
+    addLifetime(merged.lifetime, ledger.lifetime);
+    for (const session of ledger.sessions) {
+      if (seenSessions.has(session.sessionId)) continue;
+      seenSessions.add(session.sessionId);
+      merged.sessions.push(session);
+    }
+    if (ledger.wasteFlags) {
+      for (const flag of ledger.wasteFlags) {
+        const key = `${flag.pattern}|${flag.detectedAt}`;
+        if (seenFlagKeys.has(key)) continue;
+        seenFlagKeys.add(key);
+        wasteFlags.push(flag);
+      }
+    }
+  }
+
+  if (wasteFlags.length > 0) {
+    merged.wasteFlags = wasteFlags;
+  }
+
+  merged.sessions.sort((a, b) =>
+    a.startTimestamp.localeCompare(b.startTimestamp)
+  );
+  return merged;
+}
+
+export function aggregateTokenLedger(cwd: string): TokenLedger {
+  return aggregateTokenLedgerAt(projectDir(cwd));
+}
+
+export function aggregateTokenLedgerArchiveAt(
+  projDir: string
+): LedgerSession[] {
+  const seen = new Set<string>();
+  const archived: LedgerSession[] = [];
+
+  const sources = [
+    ...listDeviceShardsAt(projDir).map((id) =>
+      shardPath(projDir, id, "token-ledger-archive.json")
+    ),
+    join(projDir, "token-ledger-archive.json"),
+  ];
+
+  for (const path of sources) {
+    if (!existsSync(path)) continue;
+    for (const session of loadArchive(path)) {
+      if (seen.has(session.sessionId)) continue;
+      seen.add(session.sessionId);
+      archived.push(session);
+    }
+  }
+
+  archived.sort((a, b) => a.startTimestamp.localeCompare(b.startTimestamp));
+  return archived;
+}
+
+export function aggregateTokenLedgerArchive(cwd: string): LedgerSession[] {
+  return aggregateTokenLedgerArchiveAt(projectDir(cwd));
+}
+
+// ── Bug memory ─────────────────────────────────────────────────────────────
+
+export function aggregateBugMemoryAt(projDir: string): BugMemory {
+  const byId = new Map<string, BugEntry>();
+  let maxNextId = 1;
+
+  const sources = [
+    ...listDeviceShardsAt(projDir).map((id) =>
+      shardPath(projDir, id, "bug-memory.json")
+    ),
+    join(projDir, "bug-memory.json"),
+  ];
+
+  for (const path of sources) {
+    if (!existsSync(path)) continue;
+    const mem = loadBugMemory(path);
+    if (mem.nextId > maxNextId) maxNextId = mem.nextId;
+    for (const entry of mem.entries) {
+      const existing = byId.get(entry.id);
+      if (!existing) {
+        byId.set(entry.id, { ...entry });
+        continue;
+      }
+      existing.occurrenceCount = Math.max(
+        existing.occurrenceCount,
+        entry.occurrenceCount
+      );
+      if (entry.lastSeenAt > existing.lastSeenAt) {
+        existing.lastSeenAt = entry.lastSeenAt;
+      }
+      if (entry.createdAt < existing.createdAt) {
+        existing.createdAt = entry.createdAt;
+      }
+      const tags = new Set([...existing.tags, ...entry.tags]);
+      existing.tags = [...tags];
+      const related = new Set([
+        ...existing.relatedBugIds,
+        ...entry.relatedBugIds,
+      ]);
+      existing.relatedBugIds = [...related];
+    }
+  }
+
+  return {
+    entries: [...byId.values()].sort((a, b) =>
+      a.lastSeenAt < b.lastSeenAt ? 1 : -1
+    ),
+    nextId: maxNextId,
+  };
+}
+
+export function aggregateBugMemory(cwd: string): BugMemory {
+  return aggregateBugMemoryAt(projectDir(cwd));
+}
+
+// ── Action log ─────────────────────────────────────────────────────────────
+
+export function aggregateActionLogAt(projDir: string): string {
+  type Block = { date: string; content: string; offset: number };
+  const blocks: Block[] = [];
+  let order = 0;
+
+  const sources = [
+    ...listDeviceShardsAt(projDir).map((id) =>
+      shardPath(projDir, id, "action-log.md")
+    ),
+    join(projDir, "action-log.md"),
+  ];
+
+  for (const path of sources) {
+    if (!existsSync(path)) continue;
+    const content = safeReadLog(path);
+    if (!content) continue;
+    const sessions = parseLogSessions(content);
+    for (const session of sessions) {
+      blocks.push({
+        date: session.date,
+        content: session.content,
+        offset: order++,
+      });
+    }
+  }
+
+  blocks.sort((a, b) => {
+    if (a.date !== b.date) return a.date.localeCompare(b.date);
+    return a.offset - b.offset;
+  });
+
+  return blocks.map((b) => b.content).join("");
+}
+
+export function aggregateActionLog(cwd: string): string {
+  return aggregateActionLogAt(projectDir(cwd));
+}
+
+// ── Learning memory ────────────────────────────────────────────────────────
+
+export function aggregateLearningMemoryAt(projDir: string): LearningMemory {
+  const canonicalPath = join(projDir, "learning-memory.md");
+  let merged: LearningMemory;
+  if (existsSync(canonicalPath)) {
+    try {
+      merged = parseLearningMemory(readFileSync(canonicalPath, "utf-8"));
+    } catch {
+      merged = createEmptyLearningMemory("unknown");
+    }
+  } else {
+    merged = createEmptyLearningMemory("unknown");
+  }
+
+  for (const sidecarPath of listLearningMemorySidecarPathsAt(projDir)) {
+    let sidecar: LearningMemory;
+    try {
+      sidecar = parseLearningMemory(readFileSync(sidecarPath, "utf-8"));
+    } catch {
+      continue;
+    }
+
+    if (
+      merged.projectName === "unknown" &&
+      sidecar.projectName !== "unknown"
+    ) {
+      merged.projectName = sidecar.projectName;
+    }
+
+    for (const section of Object.keys(sidecar.sections) as SectionName[]) {
+      const existing = new Set(
+        merged.sections[section].map((e) => e.trim().toLowerCase())
+      );
+      for (const entry of sidecar.sections[section]) {
+        const norm = entry.trim().toLowerCase();
+        if (existing.has(norm)) continue;
+        existing.add(norm);
+        merged.sections[section].push(entry);
+      }
+    }
+  }
+
+  return merged;
+}
+
+export function aggregateLearningMemory(cwd: string): LearningMemory {
+  return aggregateLearningMemoryAt(projectDir(cwd));
+}

package/src/core/state-counters.ts

@@ -0,0 +1,46 @@
+import { atomicWriteJson, safeReadJson } from "./fs-utils";
+import { fileIndexCountersPath } from "./paths";
+
+// Per-device telemetry counters. Lives at projects/<id>/.mink-state-counters.json
+// and is gitignored so each device's counts never collide. Aggregated views
+// (dashboard, status) sum across devices via aggregateStateCounters().
+
+export interface StateCounters {
+  fileIndexHits: number;
+  fileIndexMisses: number;
+}
+
+function emptyCounters(): StateCounters {
+  return { fileIndexHits: 0, fileIndexMisses: 0 };
+}
+
+function isStateCounters(value: unknown): value is StateCounters {
+  if (value === null || typeof value !== "object") return false;
+  const obj = value as Record<string, unknown>;
+  return (
+    typeof obj.fileIndexHits === "number" &&
+    typeof obj.fileIndexMisses === "number"
+  );
+}
+
+export function loadCounters(cwd: string): StateCounters {
+  const raw = safeReadJson(fileIndexCountersPath(cwd));
+  if (raw !== null && isStateCounters(raw)) return raw;
+  return emptyCounters();
+}
+
+export function saveCounters(cwd: string, counters: StateCounters): void {
+  atomicWriteJson(fileIndexCountersPath(cwd), counters);
+}
+
+export function incrementFileIndexHit(cwd: string): void {
+  const c = loadCounters(cwd);
+  c.fileIndexHits++;
+  saveCounters(cwd, c);
+}
+
+export function incrementFileIndexMiss(cwd: string): void {
+  const c = loadCounters(cwd);
+  c.fileIndexMisses++;
+  saveCounters(cwd, c);
+}