@drewpayment/mink 0.11.0-beta.1 → 0.11.0-beta.3

package/src/commands/sync-migrate.ts

@@ -6,6 +6,7 @@ import {
   writeFileSync,
   readFileSync,
   renameSync,
+  rmSync,
   unlinkSync,
 } from "fs";
 import { join } from "path";
@@ -236,7 +237,24 @@ function listProjectsNeedingMigration(): string[] {
 // Idempotent: re-running after a clean pass walks every project, finds every
 // id matches its directory name, and does nothing.
 
-export type IdentityPlanAction = "rename" | "skip-converged" | "skip-no-cwd" | "skip-unchanged";
+// Plan actions:
+//   rename          old dir present, new dir absent → rename old → new, record alias.
+//   skip-converged  old dir + new dir both present, alias NOT yet recorded → record
+//                   alias on new meta and evict old dir to .identity-rollback/. Named
+//                   "skip-converged" because the rename itself is unnecessary; the
+//                   convergence work (alias + eviction) is the action.
+//   skip-evict      old dir + new dir both present, alias already recorded → only
+//                   evict the old dir. Reached when a previous migration recorded
+//                   the alias but didn't (or couldn't) finish evicting. Without
+//                   this, dry-run would keep proposing skip-converged forever.
+//   skip-no-cwd     project's working-copy path is on a different device — leave alone.
+//   skip-unchanged  newId === oldId — no work needed at all.
+export type IdentityPlanAction =
+  | "rename"
+  | "skip-converged"
+  | "skip-evict"
+  | "skip-no-cwd"
+  | "skip-unchanged";
 
 export interface IdentityPlanEntry {
   oldId: string;
@@ -248,9 +266,15 @@ export interface IdentityPlanEntry {
 
 // Walks every project on disk and returns the rename plan without touching it.
 // Backbone for both --dry-run and the real migration so they share logic.
-export function planIdentityMigration(): IdentityPlanEntry[] {
+//
+// Accepts an optional `flagOverride` so callers that have already snapshotted
+// `projects.identity` (e.g. migrateSyncLayout, before its git-stash) can pass
+// the snapshot in rather than re-reading from disk inside a stash window where
+// the config file's uncommitted writes are temporarily hidden.
+export function planIdentityMigration(flagOverride?: string): IdentityPlanEntry[] {
   const plan: IdentityPlanEntry[] = [];
-  if (resolveConfigValue("projects.identity").value !== "git-remote") {
+  const flag = flagOverride ?? resolveConfigValue("projects.identity").value;
+  if (flag !== "git-remote") {
     return plan;
   }
 
@@ -288,7 +312,10 @@ export function planIdentityMigration(): IdentityPlanEntry[] {
 
     let newId: string;
     try {
-      newId = resolveProjectIdentity(meta.cwd).id;
+      newId = resolveProjectIdentity(
+        meta.cwd,
+        flag === "git-remote" || flag === "path-derived" ? flag : undefined
+      ).id;
     } catch {
       continue;
     }
@@ -300,12 +327,23 @@ export function planIdentityMigration(): IdentityPlanEntry[] {
 
     const newProjDir = join(projectsRoot, newId);
     if (existsSync(newProjDir)) {
+      // If the canonical (new) project already records this oldId in its
+      // aliases list, the convergence bookkeeping is already done — only the
+      // leftover old directory remains to be cleaned up. Surfacing this as a
+      // distinct action (skip-evict) makes dry-run idempotent: once the alias
+      // is recorded AND the old directory is gone, the planner stops seeing
+      // the project entirely. Pre-fix it would keep proposing the same
+      // skip-converged action forever.
+      const newMeta = getProjectMeta(newProjDir);
+      const aliasAlreadyRecorded = newMeta?.aliases?.includes(oldId) ?? false;
       plan.push({
         oldId,
         newId,
         cwd: meta.cwd,
-        action: "skip-converged",
-        reason: "destination already exists (from sync); alias-only update",
+        action: aliasAlreadyRecorded ? "skip-evict" : "skip-converged",
+        reason: aliasAlreadyRecorded
+          ? "alias already recorded; will evict leftover old directory"
+          : "destination already exists (from sync); will record alias and evict old directory",
       });
       continue;
     }
@@ -358,26 +396,61 @@ function copyDirRecursive(src: string, dest: string, excludeNames: Set<string>):
   }
 }
 
-function migrateProjectIdentities(deviceId: string): {
+// Accepts the identity-mode value as a parameter so the caller can snapshot it
+// before any disk side-effects (notably the migrating git-stash in
+// migrateSyncLayout, which would hide uncommitted writes to the config file
+// that drives this very decision). Falls back to a fresh read for callers that
+// don't operate inside a stash window (e.g. session-start triggers and the
+// --dry-run path).
+export interface IdentityMigrationOutcome {
   renamed: number;
+  converged: number;
+  evicted: number;
   visited: number;
   backupDir: string | null;
-} {
-  if (resolveConfigValue("projects.identity").value !== "git-remote") {
-    return { renamed: 0, visited: 0, backupDir: null };
+  renames: Array<{ from: string; to: string }>;
+  evictions: string[];
+}
+
+function migrateProjectIdentities(
+  deviceId: string,
+  flag: string = resolveConfigValue("projects.identity").value
+): IdentityMigrationOutcome {
+  if (flag !== "git-remote") {
+    return {
+      renamed: 0,
+      converged: 0,
+      evicted: 0,
+      visited: 0,
+      backupDir: null,
+      renames: [],
+      evictions: [],
+    };
   }
 
-  const plan = planIdentityMigration();
-  const willRename = plan.filter((p) => p.action === "rename");
+  const plan = planIdentityMigration(flag);
+  // Any action that moves an old directory aside needs a backup destination.
+  // rename, skip-converged (record alias + evict), and skip-evict (alias
+  // already recorded; only evict) all qualify.
+  const willTouchOldDir = plan.filter(
+    (p) =>
+      p.action === "rename" ||
+      p.action === "skip-converged" ||
+      p.action === "skip-evict"
+  );
 
   // Compute the backup root up-front so all snapshots for this migration pass
   // land in one timestamped directory the user can find and reason about.
   let backupRoot: string | null = null;
-  if (willRename.length > 0) {
+  if (willTouchOldDir.length > 0) {
     backupRoot = identityBackupRoot(ensureIdentityBackupTimestamp());
   }
 
   let renamed = 0;
+  let converged = 0;
+  let evicted = 0;
+  const renames: Array<{ from: string; to: string }> = [];
+  const evictions: string[] = [];
   let visited = plan.length;
   const projectsRoot = join(minkRoot(), "projects");
 
@@ -394,16 +467,53 @@ function migrateProjectIdentities(deviceId: string): {
       }
     }
 
-    if (entry.action === "skip-converged" && entry.newId) {
+    if (
+      (entry.action === "skip-converged" || entry.action === "skip-evict") &&
+      entry.newId
+    ) {
       const newProjDir = join(projectsRoot, entry.newId);
+      // Record the alias and lift the device path before evicting — if the
+      // canonical meta is broken (read returns null in addProjectAlias), the
+      // safer path is to leave the old directory alone rather than discard
+      // it without ever surfacing the alias. We detect that case below.
+      let aliasOnRecord = false;
       try {
-        addProjectAlias(newProjDir, entry.oldId);
+        if (entry.action === "skip-evict") {
+          aliasOnRecord = true;
+        } else {
+          addProjectAlias(newProjDir, entry.oldId);
+          const newMeta = getProjectMeta(newProjDir);
+          aliasOnRecord = newMeta?.aliases?.includes(entry.oldId) ?? false;
+        }
         if (entry.cwd) {
           setProjectPathForDevice(newProjDir, deviceId, entry.cwd);
         }
       } catch {
         // best-effort
       }
+
+      if (aliasOnRecord && backupRoot) {
+        // Snapshot the old dir before eviction so any local-only state
+        // (writes that landed here before sync converged) is recoverable.
+        const ok = backupProjectForRollback(
+          oldProjDir,
+          join(backupRoot, entry.oldId)
+        );
+        if (ok) {
+          let removed = false;
+          try {
+            rmSync(oldProjDir, { recursive: true, force: true });
+            removed = true;
+          } catch {
+            // best-effort; leave the directory rather than partially deleted
+          }
+          if (removed) {
+            evictions.push(entry.oldId);
+            evicted++;
+            if (entry.action === "skip-converged") converged++;
+          }
+        }
+      }
       continue;
     }
 
@@ -438,9 +548,18 @@ function migrateProjectIdentities(deviceId: string): {
       // best-effort
     }
     renamed++;
+    renames.push({ from: entry.oldId, to: entry.newId });
   }
 
-  return { renamed, visited, backupDir: backupRoot };
+  return {
+    renamed,
+    converged,
+    evicted,
+    visited,
+    backupDir: backupRoot,
+    renames,
+    evictions,
+  };
 }
 
 // ── v3 identity rollback ──────────────────────────────────────────────────
@@ -527,6 +646,7 @@ export interface MigrateResult {
   fromVersion: number;
   toVersion: number;
   message?: string;
+  identity?: IdentityMigrationOutcome;
 }
 
 // Idempotent. Safe to invoke from `mink sync migrate` directly or from a
@@ -542,6 +662,11 @@ export interface MigrateResult {
 export function migrateSyncLayout(): MigrateResult {
   const fromVersion = readSyncVersion();
   const pending = listProjectsNeedingMigration();
+  // Snapshot the identity mode BEFORE the migrating stash below. The stash
+  // hides any uncommitted edits to ~/.mink/config — including the very
+  // `projects.identity = git-remote` write that should be driving this
+  // migration. Reading the flag after the stash would see the stale,
+  // last-committed config and the v3 identity step would no-op.
   const identityMode = resolveConfigValue("projects.identity").value;
   if (
     fromVersion >= MINK_SYNC_VERSION &&
@@ -611,9 +736,19 @@ export function migrateSyncLayout(): MigrateResult {
     // v3 identity migration: rename per-project directories to their stable
     // git-derived identifier when the user has opted in. Cheap no-op when the
     // flag is off or every project's identifier already matches its directory.
-    let identity = { renamed: 0, visited: 0 };
+    // Pass the pre-stash snapshot of identityMode so we don't re-read the
+    // config from a stash-hidden working tree.
+    let identity: IdentityMigrationOutcome = {
+      renamed: 0,
+      converged: 0,
+      evicted: 0,
+      visited: 0,
+      backupDir: null,
+      renames: [],
+      evictions: [],
+    };
     try {
-      identity = migrateProjectIdentities(deviceId);
+      identity = migrateProjectIdentities(deviceId, identityMode);
     } catch {
       // best-effort; never block the rest of migration
     }
@@ -625,16 +760,19 @@ export function migrateSyncLayout(): MigrateResult {
       writeSyncVersion(MINK_SYNC_VERSION);
     }
 
-    if (isSyncInitialized() && (processed > 0 || identity.renamed > 0)) {
+    if (
+      isSyncInitialized() &&
+      (processed > 0 || identity.renamed > 0 || identity.evicted > 0)
+    ) {
       // Skip the lock file — it's part of migration coordination, not state.
       gitSafe("add -A");
       gitSafe(`reset HEAD ".sync-migrate.lock"`);
-      const summary =
-        identity.renamed > 0
-          ? `${processed} projects, ${identity.renamed} renamed for identity v3`
-          : `${processed} projects`;
+      const identityNote =
+        identity.renamed > 0 || identity.evicted > 0
+          ? `, ${identity.renamed} renamed + ${identity.evicted} evicted for identity v3`
+          : "";
       gitSafe(
-        `commit -m "mink: migrate sync layout v${fromVersion} -> v${MINK_SYNC_VERSION} (device ${deviceId.slice(0, 8)}, ${summary})"`
+        `commit -m "mink: migrate sync layout v${fromVersion} -> v${MINK_SYNC_VERSION} (device ${deviceId.slice(0, 8)}, ${processed} projects${identityNote})"`
       );
     }
 
@@ -646,6 +784,7 @@ export function migrateSyncLayout(): MigrateResult {
       ranMigration: true,
       fromVersion,
       toVersion: MINK_SYNC_VERSION,
+      identity,
     };
   } finally {
     releaseLock();
@@ -671,20 +810,24 @@ export function syncMigrateCommand(args: string[] = []): void {
     }
     const renames = plan.filter((p) => p.action === "rename");
     const converged = plan.filter((p) => p.action === "skip-converged");
+    const evictOnly = plan.filter((p) => p.action === "skip-evict");
     const skippedNoCwd = plan.filter((p) => p.action === "skip-no-cwd");
     const unchanged = plan.filter((p) => p.action === "skip-unchanged");
 
     console.log(
-      `[mink] sync migrate --dry-run: ${renames.length} rename(s), ${converged.length} alias-only, ${skippedNoCwd.length} skipped (no cwd), ${unchanged.length} unchanged`
+      `[mink] sync migrate --dry-run: ${renames.length} rename(s), ${converged.length} converge (alias + evict), ${evictOnly.length} evict-only, ${skippedNoCwd.length} skipped (no cwd), ${unchanged.length} unchanged`
     );
     for (const p of renames) {
-      console.log(`  rename: ${p.oldId} → ${p.newId}`);
+      console.log(`  rename:   ${p.oldId} → ${p.newId}`);
     }
     for (const p of converged) {
-      console.log(`  alias:  ${p.oldId} → ${p.newId} (already on disk)`);
+      console.log(`  converge: ${p.oldId} → ${p.newId} (record alias on ${p.newId}, evict ${p.oldId} to .identity-rollback/)`);
+    }
+    for (const p of evictOnly) {
+      console.log(`  evict:    ${p.oldId} → .identity-rollback/ (alias already on ${p.newId})`);
     }
     for (const p of skippedNoCwd) {
-      console.log(`  skip:   ${p.oldId} — ${p.reason}`);
+      console.log(`  skip:     ${p.oldId} — ${p.reason}`);
     }
     return;
   }
@@ -724,4 +867,19 @@ export function syncMigrateCommand(args: string[] = []): void {
   console.log(
     `[mink] sync migrate: v${result.fromVersion} → v${result.toVersion} complete`
   );
+  const identity = result.identity;
+  if (identity && (identity.renamed > 0 || identity.evicted > 0)) {
+    console.log(
+      `  identity: ${identity.renamed} renamed, ${identity.converged} converged, ${identity.evicted} evicted`
+    );
+    for (const r of identity.renames) {
+      console.log(`    renamed: ${r.from} → ${r.to}`);
+    }
+    for (const id of identity.evictions) {
+      console.log(`    evicted: ${id} → .identity-rollback/`);
+    }
+    if (identity.backupDir) {
+      console.log(`  rollback snapshot: ${identity.backupDir}`);
+    }
+  }
 }

package/src/core/project-id.ts

@@ -136,8 +136,16 @@ function readIdentityMode(): "path-derived" | "git-remote" {
   return "path-derived";
 }
 
-export function resolveProjectIdentity(cwd: string): ProjectIdentity {
-  const mode = readIdentityMode();
+// Accepts an optional `modeOverride` so callers that have already snapshotted
+// `projects.identity` (e.g. the v3 migration, which runs inside a git-stash
+// window where the config file's uncommitted writes are hidden from disk) can
+// pass the snapshot in. Without the override, the internal mode read can
+// disagree with the caller's view of the world and produce the wrong id.
+export function resolveProjectIdentity(
+  cwd: string,
+  modeOverride?: "path-derived" | "git-remote"
+): ProjectIdentity {
+  const mode = modeOverride ?? readIdentityMode();
   if (mode === "path-derived") {
     return { id: generateProjectId(cwd), source: "path-derived" };
   }

package/src/core/sync.ts

@@ -51,6 +51,13 @@ config.local
 # Migration coordination — never sync this
 .sync-migrate.lock
 
+# Per-device identity migration recovery snapshots — local recovery state
+# for the migrating device, not authoritative project state. A device that
+# needs to recover from its migration must do so from its own snapshot;
+# syncing would make rollback dirs appear on devices that never produced
+# the corresponding migration.
+.identity-rollback/
+
 # Local backups and per-device caches — machine-specific snapshots
 projects/*/backups/
 projects/*/session.json