@drewpayment/mink 0.8.0 → 0.9.1

package/src/commands/sync-migrate.ts

@@ -0,0 +1,330 @@
+import {
+  existsSync,
+  readdirSync,
+  statSync,
+  mkdirSync,
+  writeFileSync,
+  readFileSync,
+  renameSync,
+  unlinkSync,
+} from "fs";
+import { join } from "path";
+import { execSync } from "child_process";
+import {
+  minkRoot,
+  fileIndexCountersPath,
+} from "../core/paths";
+import {
+  MINK_SYNC_VERSION,
+  readSyncVersion,
+  writeSyncVersion,
+  ensureGitignore,
+  ensureGitAttributes,
+  ensureMergeDriversRegistered,
+  isSyncInitialized,
+} from "../core/sync";
+import { getOrCreateDeviceId } from "../core/device";
+import { atomicWriteJson, safeReadJson } from "../core/fs-utils";
+import type { FileIndex } from "../types/file-index";
+
+const MIGRATE_LOCK = ".sync-migrate.lock";
+const MIGRATE_LOCK_STALE_MS = 300_000; // 5 minutes
+const MIGRATE_BUDGET_MS = 5_000;
+
+function gitSafe(args: string, timeoutMs: number = 5_000): string | null {
+  try {
+    return execSync(`git ${args}`, {
+      cwd: minkRoot(),
+      timeout: timeoutMs,
+      stdio: ["pipe", "pipe", "pipe"],
+    })
+      .toString()
+      .trim();
+  } catch {
+    return null;
+  }
+}
+
+function acquireLock(): boolean {
+  const path = join(minkRoot(), MIGRATE_LOCK);
+  if (existsSync(path)) {
+    try {
+      const ageMs = Date.now() - statSync(path).mtimeMs;
+      if (ageMs < MIGRATE_LOCK_STALE_MS) return false;
+    } catch {
+      // If stat fails, treat as stale and reclaim.
+    }
+  }
+  try {
+    writeFileSync(path, `${process.pid}\n`);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function releaseLock(): void {
+  try {
+    unlinkSync(join(minkRoot(), MIGRATE_LOCK));
+  } catch {
+    // ignore
+  }
+}
+
+// Move a file from `from` to `to` using `git mv` when possible (preserves
+// history) and a plain rename otherwise. Returns true if the move succeeded
+// or the source did not exist.
+function migrateFile(from: string, to: string): boolean {
+  if (!existsSync(from)) return true;
+  mkdirSync(join(to, ".."), { recursive: true });
+  // Prefer `git mv` so blame/history follow the file. Fall back to a plain
+  // rename if git can't handle it (e.g. the file isn't tracked yet).
+  if (gitSafe(`mv "${from}" "${to}"`) !== null) return true;
+  try {
+    renameSync(from, to);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function migrateProject(projDir: string, deviceId: string): void {
+  const shardDir = join(projDir, "state", deviceId);
+  mkdirSync(shardDir, { recursive: true });
+
+  // Move per-device-rewritten files into the device shard. `git mv` preserves
+  // history; if a sibling shard already exists for this file (re-running the
+  // migration after a partial first run), we leave the sibling alone — it's
+  // already in the right place.
+  for (const file of [
+    "token-ledger.json",
+    "token-ledger-archive.json",
+    "bug-memory.json",
+    "action-log.md",
+  ]) {
+    const legacy = join(projDir, file);
+    const shard = join(shardDir, file);
+    if (existsSync(shard)) continue;
+    migrateFile(legacy, shard);
+  }
+
+  // learning-memory.md: leave canonical in place. Touch an empty sidecar so
+  // future incremental writes have a target.
+  const sidecar = join(projDir, `learning-memory.${deviceId}.md`);
+  if (!existsSync(sidecar)) {
+    try {
+      writeFileSync(sidecar, "");
+    } catch {
+      // best-effort
+    }
+  }
+
+  // Drop session.json + scheduler-manifest.json from the index — they remain
+  // on disk but stop being synced (they're now gitignored under v2).
+  for (const f of ["session.json", "scheduler-manifest.json"]) {
+    if (existsSync(join(projDir, f))) {
+      gitSafe(`rm --cached "${join(projDir, f)}"`);
+    }
+  }
+
+  // Split file-index counters out into a per-device counter file.
+  const indexPath = join(projDir, "file-index.json");
+  if (existsSync(indexPath)) {
+    const raw = safeReadJson(indexPath) as FileIndex | null;
+    if (
+      raw &&
+      typeof raw.header === "object" &&
+      raw.header !== null &&
+      (raw.header.lifetimeHits > 0 || raw.header.lifetimeMisses > 0)
+    ) {
+      // Carry forward the existing counters so the per-device telemetry
+      // continues uninterrupted on this device.
+      atomicWriteJson(fileIndexCountersPathFor(projDir), {
+        fileIndexHits: raw.header.lifetimeHits,
+        fileIndexMisses: raw.header.lifetimeMisses,
+      });
+      raw.header.lifetimeHits = 0;
+      raw.header.lifetimeMisses = 0;
+      atomicWriteJson(indexPath, raw);
+    }
+  }
+}
+
+function fileIndexCountersPathFor(projDir: string): string {
+  return join(projDir, ".mink-state-counters.json");
+}
+
+function listProjects(): string[] {
+  const projectsRoot = join(minkRoot(), "projects");
+  if (!existsSync(projectsRoot)) return [];
+  try {
+    return readdirSync(projectsRoot)
+      .filter((name) => {
+        try {
+          return statSync(join(projectsRoot, name)).isDirectory();
+        } catch {
+          return false;
+        }
+      })
+      .map((name) => join(projectsRoot, name));
+  } catch {
+    return [];
+  }
+}
+
+// True if any legacy v1 state shape still lives at the top level of projDir
+// AND no per-device shard has been populated yet. Once a shard directory has
+// any contents, this project counts as migrated even if a stale legacy file
+// is still on disk — that's the case where the user opened a session
+// mid-migration and writes started landing in the shard. The aggregator unions
+// across legacy + shards on read, so the stale file is harmless until cleaned
+// up; what we must avoid is a permanent re-migrate loop on every session-start.
+function projectNeedsMigration(projDir: string): boolean {
+  const stateDir = join(projDir, "state");
+  if (existsSync(stateDir)) {
+    try {
+      const shards = readdirSync(stateDir).filter((d) => {
+        try {
+          return statSync(join(stateDir, d)).isDirectory();
+        } catch {
+          return false;
+        }
+      });
+      if (shards.length > 0) return false;
+    } catch {
+      // fall through
+    }
+  }
+  for (const f of [
+    "token-ledger.json",
+    "token-ledger-archive.json",
+    "bug-memory.json",
+    "action-log.md",
+  ]) {
+    if (existsSync(join(projDir, f))) return true;
+  }
+  return false;
+}
+
+function listProjectsNeedingMigration(): string[] {
+  return listProjects().filter(projectNeedsMigration);
+}
+
+export interface MigrateResult {
+  ranMigration: boolean;
+  fromVersion: number;
+  toVersion: number;
+  message?: string;
+}
+
+// Idempotent. Safe to invoke from `mink sync migrate` directly or from a
+// session-start auto-trigger when readSyncVersion() < MINK_SYNC_VERSION.
+//
+// We treat the version marker as a hint, not a gate — a previous partial run
+// (interrupted by the budget cap) may have written v2 with projects still
+// pending. We re-run as long as any project on disk still has legacy files at
+// its top level, regardless of marker.
+export function migrateSyncLayout(): MigrateResult {
+  const fromVersion = readSyncVersion();
+  const pending = listProjectsNeedingMigration();
+  if (fromVersion >= MINK_SYNC_VERSION && pending.length === 0) {
+    return {
+      ranMigration: false,
+      fromVersion,
+      toVersion: MINK_SYNC_VERSION,
+      message: `already at v${MINK_SYNC_VERSION}`,
+    };
+  }
+
+  const start = Date.now();
+
+  if (!acquireLock()) {
+    return {
+      ranMigration: false,
+      fromVersion,
+      toVersion: MINK_SYNC_VERSION,
+      message: "another migration is in progress",
+    };
+  }
+
+  try {
+    // Refresh .gitignore/.gitattributes/merge drivers regardless of whether
+    // sync is initialised — they're cheap and idempotent. The merge-driver
+    // registration is a no-op when .git/ doesn't exist.
+    ensureGitignore();
+    if (isSyncInitialized()) {
+      ensureGitAttributes();
+      ensureMergeDriversRegistered();
+    }
+
+    const deviceId = getOrCreateDeviceId();
+
+    // Stash uncommitted changes so the migrating commit doesn't sweep up
+    // unrelated edits. Best-effort — if nothing to stash, this is a no-op.
+    let stashed = false;
+    if (isSyncInitialized()) {
+      const status = gitSafe("status --porcelain");
+      if (status && status.trim().length > 0) {
+        if (gitSafe("stash push -m mink-sync-migrate") !== null) {
+          stashed = true;
+        }
+      }
+    }
+
+    // Process pending projects only — already-migrated projects are skipped
+    // for free, and we resume work from any prior partial run.
+    let processed = 0;
+    let remaining = 0;
+    for (const projDir of listProjectsNeedingMigration()) {
+      if (Date.now() - start > MIGRATE_BUDGET_MS) {
+        remaining++;
+        continue;
+      }
+      try {
+        migrateProject(projDir, deviceId);
+        processed++;
+      } catch {
+        // best-effort per project — never block migration on one project
+      }
+    }
+
+    // Only stamp the version marker once nothing is left to migrate. If we
+    // still have pending projects, leave the marker as-is so the next session
+    // knows to keep going.
+    if (remaining === 0 && listProjectsNeedingMigration().length === 0) {
+      writeSyncVersion(MINK_SYNC_VERSION);
+    }
+
+    if (isSyncInitialized() && processed > 0) {
+      // Skip the lock file — it's part of migration coordination, not state.
+      gitSafe("add -A");
+      gitSafe(`reset HEAD ".sync-migrate.lock"`);
+      gitSafe(
+        `commit -m "mink: migrate sync layout v${fromVersion} -> v${MINK_SYNC_VERSION} (device ${deviceId.slice(0, 8)}, ${processed} projects)"`
+      );
+    }
+
+    if (stashed) {
+      gitSafe("stash pop");
+    }
+
+    return {
+      ranMigration: true,
+      fromVersion,
+      toVersion: MINK_SYNC_VERSION,
+    };
+  } finally {
+    releaseLock();
+  }
+}
+
+export function syncMigrateCommand(): void {
+  const result = migrateSyncLayout();
+  if (!result.ranMigration) {
+    console.log(`[mink] sync migrate: ${result.message ?? "no-op"}`);
+    return;
+  }
+  console.log(
+    `[mink] sync migrate: v${result.fromVersion} → v${result.toVersion} complete`
+  );
+}

package/src/commands/sync.ts

@@ -7,6 +7,11 @@ import {
   isSyncInitialized,
 } from "../core/sync";
 import { setConfigValue } from "../core/global-config";
+import { runMergeDriver } from "../core/sync-merge-drivers";
+import {
+  listParkedConflicts,
+  dropParkedConflict,
+} from "../core/conflict-park";
 
 export async function sync(args: string[]): Promise<void> {
   const subcommand = args[0];
@@ -39,13 +44,82 @@ export async function sync(args: string[]): Promise<void> {
     case "disconnect":
       return handleDisconnect();
 
+    case "merge-driver":
+      return handleMergeDriver(args.slice(1));
+
+    case "reconcile":
+      return handleReconcile(args.slice(1));
+
+    case "migrate": {
+      const { syncMigrateCommand } = await import("./sync-migrate");
+      syncMigrateCommand();
+      return;
+    }
+
     default:
       console.error(`[mink] unknown sync subcommand: ${subcommand}`);
-      console.error("Usage: mink sync [init|status|push|pull|pause|resume|disconnect]");
+      console.error(
+        "Usage: mink sync [init|status|push|pull|pause|resume|disconnect|reconcile|migrate|merge-driver]"
+      );
       process.exit(1);
   }
 }
 
+function handleReconcile(args: string[]): void {
+  const sub = args[0];
+  if (sub === undefined || sub === "list") {
+    const refs = listParkedConflicts();
+    if (refs.length === 0) {
+      console.log("[mink] no parked conflicts");
+      return;
+    }
+    console.log(`[mink] ${refs.length} parked conflict ref(s):`);
+    for (const r of refs) console.log(`  ${r}`);
+    console.log(
+      "Inspect with: cd ~/.mink && git log <ref> | git diff main..<ref>"
+    );
+    console.log("Drop with:    mink sync reconcile drop <ref>");
+    return;
+  }
+  if (sub === "drop") {
+    const ref = args[1];
+    if (!ref) {
+      console.error("Usage: mink sync reconcile drop <ref>");
+      process.exit(1);
+    }
+    if (dropParkedConflict(ref)) {
+      console.log(`[mink] dropped ${ref}`);
+    } else {
+      console.error(`[mink] failed to drop ${ref} — only refs/mink/conflicts/* are droppable`);
+      process.exit(1);
+    }
+    return;
+  }
+  console.error("Usage: mink sync reconcile [list|drop <ref>]");
+  process.exit(1);
+}
+
+// Invoked by git for paths matched in .gitattributes. Always exits 0 so a
+// merge can never block — the driver itself logs warnings and falls back to
+// "ours" when inputs are unparseable.
+function handleMergeDriver(args: string[]): void {
+  const [name, basePath, oursPath, theirsPath, filePath] = args;
+  if (!name || !basePath || !oursPath || !theirsPath) {
+    console.error(
+      "Usage: mink sync merge-driver <name> <base> <ours> <theirs> [path]"
+    );
+    process.exit(0); // exit 0 so git never sees a failure here
+  }
+  const code = runMergeDriver(
+    name,
+    basePath,
+    oursPath,
+    theirsPath,
+    filePath ?? oursPath
+  );
+  process.exit(code);
+}
+
 function handleManualSync(): void {
   if (!isSyncInitialized()) {
     console.error("[mink] sync is not initialized");

package/src/commands/update.ts

@@ -1,10 +1,9 @@
-import { resolve, dirname, basename } from "path";
-import { existsSync } from "fs";
+import { resolve } from "path";
 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";
+import { buildHooksConfig, mergeHooksIntoSettings, resolveCliPath } from "./init";
 
 function parseArgs(args: string[]): {
   dryRun: boolean;
@@ -78,12 +77,8 @@ export async function update(cwd: string, args: string[]): Promise<void> {
     return;
   }
 
-  const runtime = detectRuntime();
-  const cliPath = resolve(
-    dirname(new URL(import.meta.url).pathname),
-    "../cli.ts"
-  );
-  const newHooks = buildHooksConfig(runtime, cliPath);
+  const cliPath = resolveCliPath();
+  const newHooks = buildHooksConfig(cliPath);
 
   for (const target of targets) {
     console.log(`[mink] updating: ${target.name} (${target.id})`);

package/src/core/conflict-park.ts

@@ -0,0 +1,84 @@
+import { execSync } from "child_process";
+import { existsSync } from "fs";
+import { join } from "path";
+import { minkRoot } from "./paths";
+import { getOrCreateDeviceId } from "./device";
+
+const GIT_TIMEOUT = 5_000;
+
+function git(args: string): string {
+  return execSync(`git ${args}`, {
+    cwd: minkRoot(),
+    timeout: GIT_TIMEOUT,
+    stdio: ["pipe", "pipe", "pipe"],
+  })
+    .toString()
+    .trim();
+}
+
+function gitSafe(args: string): string | null {
+  try {
+    return git(args);
+  } catch {
+    return null;
+  }
+}
+
+// Park the current local state onto a hidden ref so an unresolvable merge
+// never blocks sync. Sequence:
+//   1. If a merge is in progress, abort it cleanly (`git merge --abort`).
+//   2. Save HEAD as `refs/mink/conflicts/<deviceId>/<iso-utc>`.
+//   3. Hard-reset working tree to upstream (origin/<branch>) so subsequent
+//      writes start from a clean, fast-forwardable state.
+// Returns the parked refname (or null if the operation was a no-op or failed —
+// callers must NEVER throw on the result).
+export function parkConflictingState(reason: string): string | null {
+  const root = minkRoot();
+  const inMerge =
+    existsSync(join(root, ".git", "MERGE_HEAD")) ||
+    existsSync(join(root, ".git", "rebase-merge")) ||
+    existsSync(join(root, ".git", "rebase-apply"));
+
+  if (inMerge) {
+    gitSafe("merge --abort");
+    gitSafe("rebase --abort");
+  }
+
+  const branch = gitSafe("rev-parse --abbrev-ref HEAD") ?? "main";
+  const upstream = `origin/${branch}`;
+
+  // Don't park if there's nothing to save (HEAD already matches upstream).
+  const headSha = gitSafe("rev-parse HEAD");
+  const upstreamSha = gitSafe(`rev-parse ${upstream}`);
+  if (headSha && headSha === upstreamSha) {
+    return null;
+  }
+
+  const deviceId = getOrCreateDeviceId();
+  const iso = new Date().toISOString().replace(/[:.]/g, "-");
+  const ref = `refs/mink/conflicts/${deviceId}/${iso}`;
+
+  if (!headSha) return null;
+
+  if (gitSafe(`update-ref ${ref} ${headSha}`) === null) {
+    return null;
+  }
+  gitSafe(`reset --hard ${upstream}`);
+
+  return ref;
+}
+
+// List previously-parked conflict refs. Used by `mink sync reconcile list`.
+export function listParkedConflicts(): string[] {
+  const out = gitSafe("for-each-ref --format=%(refname) refs/mink/conflicts");
+  if (!out) return [];
+  return out
+    .split("\n")
+    .map((s) => s.trim())
+    .filter((s) => s.startsWith("refs/mink/conflicts/"));
+}
+
+export function dropParkedConflict(ref: string): boolean {
+  if (!ref.startsWith("refs/mink/conflicts/")) return false;
+  return gitSafe(`update-ref -d ${ref}`) !== null;
+}

package/src/core/dashboard-api.ts

@@ -18,6 +18,12 @@ import { loadLedger } from "./token-ledger";
 import { parseLearningMemory } from "./learning-memory";
 import { loadBugMemory } from "./bug-memory";
 import { safeReadLog, parseLogSessions } from "./action-log";
+import {
+  aggregateTokenLedger,
+  aggregateBugMemory,
+  aggregateActionLog,
+  aggregateLearningMemory,
+} from "./state-aggregator";
 import { getDaemonStatus, startDaemon, stopDaemon } from "./daemon";
 import { loadManifest, removeFromDeadLetter, saveManifest } from "./scheduler";
 import { getBuiltInTasks, executeTask } from "./task-registry";
@@ -147,8 +153,8 @@ export function loadOverview(cwd: string): OverviewPayload {
       : undefined,
   };
 
-  // Token ledger summary
-  const ledger = loadLedger(tokenLedgerPath(cwd));
+  // Token ledger summary (aggregated across all device shards + legacy)
+  const ledger = aggregateTokenLedger(cwd);
   const summary = {
     totalSessions: ledger.lifetime.totalSessions,
     totalTokens: ledger.lifetime.totalTokens,
@@ -173,7 +179,7 @@ export function loadOverview(cwd: string): OverviewPayload {
 }
 
 export function loadTokenLedgerPanel(cwd: string): TokenLedgerPayload {
-  const ledger = loadLedger(tokenLedgerPath(cwd));
+  const ledger = aggregateTokenLedger(cwd);
   return {
     lifetime: ledger.lifetime,
     sessions: ledger.sessions,
@@ -216,42 +222,17 @@ export function loadSchedulerPanel(cwd: string): SchedulerPayload {
 }
 
 export function loadLearningMemoryPanel(cwd: string): LearningMemory {
-  const memPath = learningMemoryPath(cwd);
-  if (!existsSync(memPath)) {
-    return {
-      projectName: "unknown",
-      sections: {
-        "User Preferences": [],
-        "Key Learnings": [],
-        "Do-Not-Repeat": [],
-        "Decision Log": [],
-      },
-    };
-  }
-  try {
-    const content = readFileSync(memPath, "utf-8");
-    return parseLearningMemory(content);
-  } catch {
-    return {
-      projectName: "unknown",
-      sections: {
-        "User Preferences": [],
-        "Key Learnings": [],
-        "Do-Not-Repeat": [],
-        "Decision Log": [],
-      },
-    };
-  }
+  return aggregateLearningMemory(cwd);
 }
 
 export function loadActionLogPanel(cwd: string): ActionLogPayload {
-  const content = safeReadLog(actionLogPath(cwd));
+  const content = aggregateActionLog(cwd);
   const sessions = parseLogSessions(content);
   return { sessions };
 }
 
 export function loadBugLogPanel(cwd: string): BugLogPayload {
-  const memory = loadBugMemory(bugMemoryPath(cwd));
+  const memory = aggregateBugMemory(cwd);
   return { entries: memory.entries, nextId: memory.nextId };
 }