@drewpayment/mink 0.10.1 → 0.11.0-beta.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@drewpayment/mink",
-  "version": "0.10.1",
+  "version": "0.11.0-beta.1",
   "description": "A hidden presence that moves alongside the developer — token efficiency and cross-project wiki for AI coding assistants",
   "type": "module",
   "bin": {

package/src/commands/init.ts

@@ -2,8 +2,10 @@ 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 { resolveProjectIdentity } from "../core/project-id";
 import { atomicWriteJson, atomicWriteText, safeReadJson } from "../core/fs-utils";
+import { getOrCreateDeviceId } from "../core/device";
+import { getRepoRoot, getRepoRemote } from "../core/git-identity";
 import {
   isWikiEnabled,
   isVaultInitialized,
@@ -176,21 +178,32 @@ export async function init(cwd: string): Promise<void> {
 
   mkdirSync(dir, { recursive: true });
 
-  const projectId = generateProjectId(cwd);
+  const identity = resolveProjectIdentity(cwd);
+  const projectId = identity.id;
 
   // Detect notes project type
   const isNotesProject =
     isWikiEnabled() && isVaultInitialized() && isInsideVault(cwd);
 
-  // Write project metadata
+  // Write project metadata. Lift cwd into the per-device map alongside the
+  // legacy singular field so older mink versions (which only read `cwd`) keep
+  // working after a downgrade and new versions can track each device's path.
   const metaPath = projectMetaPath(cwd);
   const existingMeta = safeReadJson(metaPath) as Record<string, unknown> | null;
+  const deviceId = getOrCreateDeviceId();
+  const existingPathsByDevice =
+    existingMeta?.pathsByDevice &&
+    typeof existingMeta.pathsByDevice === "object" &&
+    !Array.isArray(existingMeta.pathsByDevice)
+      ? (existingMeta.pathsByDevice as Record<string, string>)
+      : {};
   atomicWriteJson(metaPath, {
     ...(existingMeta ?? {}),
     cwd,
     name: basename(cwd),
     initTimestamp: existingMeta?.initTimestamp ?? new Date().toISOString(),
     version: "0.1.0",
+    pathsByDevice: { ...existingPathsByDevice, [deviceId]: cwd },
     ...(isNotesProject ? { projectType: "notes" } : {}),
   });
 
@@ -201,13 +214,25 @@ export async function init(cwd: string): Promise<void> {
     console.log(`  rule:     ${rulePath}`);
   } else {
     console.log(`[mink] initialized`);
-    console.log(`  project:  ${projectId}`);
+    console.log(`  project:  ${projectId} (${identity.source})`);
     console.log(`  state:    ${dir}`);
     console.log(`  runtime:  ${runtime}`);
     console.log(`  hooks:    ${settingsPath}`);
     console.log(`  rule:     ${rulePath}`);
   }
 
+  // Surface a one-time hint when the project is in a git repo with no remote
+  // configured — that's the only case where stable cross-machine identity is
+  // a config-fix away.
+  if (identity.source === "path-derived") {
+    const root = getRepoRoot(cwd);
+    if (root && !getRepoRemote(cwd)) {
+      console.log(
+        `  note:     this repo has no remote configured. Project state will not unify across machines until you add one and run \`mink config projects.identity git-remote\`.`
+      );
+    }
+  }
+
   // Run initial scan
   const { scan } = await import("./scan");
   scan(cwd, { check: false });

package/src/commands/note.ts

@@ -6,7 +6,7 @@ import {
   resolveVaultPath,
 } from "../core/vault";
 import { resolveConfigValue } from "../core/global-config";
-import { generateProjectId } from "../core/project-id";
+import { projectIdFor } from "../core/project-id";
 import {
   createNote,
   appendToDaily,
@@ -180,7 +180,7 @@ function detectSourceProject(cwd: string): string | undefined {
     const vaultPath = resolveVaultPath();
     // Don't mark notes created from within the vault itself
     if (cwd.startsWith(vaultPath)) return undefined;
-    return generateProjectId(cwd);
+    return projectIdFor(cwd);
   } catch {
     return undefined;
   }

package/src/commands/session-start.ts

@@ -24,10 +24,16 @@ export function sessionStart(cwd: string): void {
     // Never crash hooks
   }
 
-  // One-shot migration to sync layout v2. Idempotent re-run is a no-op.
+  // One-shot migration to the current sync layout. Idempotent re-run is a
+  // no-op. We also re-trigger when projects.identity=git-remote so a user who
+  // flips the flag after the version has stamped still gets project directories
+  // renamed to their stable identifier on the next session-start.
   try {
     const { readSyncVersion, MINK_SYNC_VERSION } = require("../core/sync");
-    if (readSyncVersion() < MINK_SYNC_VERSION) {
+    const { resolveConfigValue } = require("../core/global-config");
+    const identityOn =
+      resolveConfigValue("projects.identity").value === "git-remote";
+    if (readSyncVersion() < MINK_SYNC_VERSION || identityOn) {
       const { migrateSyncLayout } = require("./sync-migrate");
       migrateSyncLayout();
     }

package/src/commands/sync-migrate.ts

@@ -25,6 +25,16 @@ import {
 } from "../core/sync";
 import { getOrCreateDeviceId } from "../core/device";
 import { atomicWriteJson, safeReadJson } from "../core/fs-utils";
+import {
+  resolveProjectIdentity,
+  generateProjectId,
+} from "../core/project-id";
+import {
+  getProjectMeta,
+  addProjectAlias,
+  setProjectPathForDevice,
+} from "../core/project-registry";
+import { resolveConfigValue } from "../core/global-config";
 import type { FileIndex } from "../types/file-index";
 
 const MIGRATE_LOCK = ".sync-migrate.lock";
@@ -210,6 +220,308 @@ function listProjectsNeedingMigration(): string[] {
   return listProjects().filter(projectNeedsMigration);
 }
 
+// ── v3 identity migration ─────────────────────────────────────────────────
+//
+// When `projects.identity = git-remote`, walks every project on disk and:
+//   1. Computes its new identifier from the recorded working-copy path.
+//   2. If the new identifier differs from the on-disk directory name, snapshots
+//      the project to a rollback backup, then renames the directory (preferring
+//      `git mv` so history is preserved when sync is initialised), records the
+//      old identifier as an alias, and lifts the singular `cwd` into the
+//      per-device path map keyed by this device.
+//   3. If the working-copy path is missing from the local filesystem (the
+//      project's repo was cloned on a different machine), the project is left
+//      alone — the device that owns the cwd will handle the rename.
+//
+// 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";
+
+export interface IdentityPlanEntry {
+  oldId: string;
+  newId: string | null;
+  cwd: string | null;
+  action: IdentityPlanAction;
+  reason?: string;
+}
+
+// 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[] {
+  const plan: IdentityPlanEntry[] = [];
+  if (resolveConfigValue("projects.identity").value !== "git-remote") {
+    return plan;
+  }
+
+  const projectsRoot = join(minkRoot(), "projects");
+  if (!existsSync(projectsRoot)) return plan;
+
+  let entries: string[];
+  try {
+    entries = readdirSync(projectsRoot);
+  } catch {
+    return plan;
+  }
+
+  for (const oldId of entries) {
+    const oldProjDir = join(projectsRoot, oldId);
+    try {
+      if (!statSync(oldProjDir).isDirectory()) continue;
+    } catch {
+      continue;
+    }
+
+    const meta = getProjectMeta(oldProjDir);
+    if (!meta) continue;
+
+    if (!existsSync(meta.cwd)) {
+      plan.push({
+        oldId,
+        newId: null,
+        cwd: meta.cwd,
+        action: "skip-no-cwd",
+        reason: "working-copy path not reachable on this device",
+      });
+      continue;
+    }
+
+    let newId: string;
+    try {
+      newId = resolveProjectIdentity(meta.cwd).id;
+    } catch {
+      continue;
+    }
+
+    if (newId === oldId) {
+      plan.push({ oldId, newId, cwd: meta.cwd, action: "skip-unchanged" });
+      continue;
+    }
+
+    const newProjDir = join(projectsRoot, newId);
+    if (existsSync(newProjDir)) {
+      plan.push({
+        oldId,
+        newId,
+        cwd: meta.cwd,
+        action: "skip-converged",
+        reason: "destination already exists (from sync); alias-only update",
+      });
+      continue;
+    }
+
+    plan.push({ oldId, newId, cwd: meta.cwd, action: "rename" });
+  }
+  return plan;
+}
+
+const IDENTITY_BACKUP_DIRNAME = ".identity-rollback";
+
+function identityBackupRoot(timestamp: string): string {
+  return join(minkRoot(), IDENTITY_BACKUP_DIRNAME, timestamp);
+}
+
+function ensureIdentityBackupTimestamp(): string {
+  const now = new Date();
+  return `${now.getUTCFullYear()}${String(now.getUTCMonth() + 1).padStart(2, "0")}${String(
+    now.getUTCDate()
+  ).padStart(2, "0")}-${String(now.getUTCHours()).padStart(2, "0")}${String(
+    now.getUTCMinutes()
+  ).padStart(2, "0")}${String(now.getUTCSeconds()).padStart(2, "0")}`;
+}
+
+// Copies a project directory tree to the rollback backup. Skips `backups/` so
+// nested backups don't double the snapshot size. Returns the backup path or
+// null on failure (caller logs but does not abort migration on backup failure).
+function backupProjectForRollback(srcDir: string, backupDir: string): string | null {
+  try {
+    mkdirSync(backupDir, { recursive: true });
+    copyDirRecursive(srcDir, backupDir, new Set(["backups"]));
+    return backupDir;
+  } catch {
+    return null;
+  }
+}
+
+function copyDirRecursive(src: string, dest: string, excludeNames: Set<string>): void {
+  mkdirSync(dest, { recursive: true });
+  const entries = readdirSync(src, { withFileTypes: true });
+  for (const entry of entries) {
+    if (excludeNames.has(entry.name)) continue;
+    const srcPath = join(src, entry.name);
+    const destPath = join(dest, entry.name);
+    if (entry.isDirectory()) {
+      copyDirRecursive(srcPath, destPath, excludeNames);
+    } else if (entry.isFile()) {
+      writeFileSync(destPath, readFileSync(srcPath));
+    }
+  }
+}
+
+function migrateProjectIdentities(deviceId: string): {
+  renamed: number;
+  visited: number;
+  backupDir: string | null;
+} {
+  if (resolveConfigValue("projects.identity").value !== "git-remote") {
+    return { renamed: 0, visited: 0, backupDir: null };
+  }
+
+  const plan = planIdentityMigration();
+  const willRename = plan.filter((p) => p.action === "rename");
+
+  // 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) {
+    backupRoot = identityBackupRoot(ensureIdentityBackupTimestamp());
+  }
+
+  let renamed = 0;
+  let visited = plan.length;
+  const projectsRoot = join(minkRoot(), "projects");
+
+  for (const entry of plan) {
+    const oldProjDir = join(projectsRoot, entry.oldId);
+
+    // Lift cwd into pathsByDevice for every project we can see, even
+    // skip-unchanged ones, so older records gain the multi-device shape.
+    if (entry.cwd && entry.action !== "skip-no-cwd") {
+      try {
+        setProjectPathForDevice(oldProjDir, deviceId, entry.cwd);
+      } catch {
+        // best-effort
+      }
+    }
+
+    if (entry.action === "skip-converged" && entry.newId) {
+      const newProjDir = join(projectsRoot, entry.newId);
+      try {
+        addProjectAlias(newProjDir, entry.oldId);
+        if (entry.cwd) {
+          setProjectPathForDevice(newProjDir, deviceId, entry.cwd);
+        }
+      } catch {
+        // best-effort
+      }
+      continue;
+    }
+
+    if (entry.action !== "rename" || !entry.newId) continue;
+
+    // Snapshot the project before the rename so the user can recover if the
+    // alias-based rollback ever fails.
+    if (backupRoot) {
+      backupProjectForRollback(oldProjDir, join(backupRoot, entry.oldId));
+    }
+
+    const newProjDir = join(projectsRoot, entry.newId);
+    const moved =
+      gitSafe(`mv "${oldProjDir}" "${newProjDir}"`) !== null ||
+      (() => {
+        try {
+          renameSync(oldProjDir, newProjDir);
+          return true;
+        } catch {
+          return false;
+        }
+      })();
+
+    if (!moved) continue;
+
+    try {
+      addProjectAlias(newProjDir, entry.oldId);
+      if (entry.cwd) {
+        setProjectPathForDevice(newProjDir, deviceId, entry.cwd);
+      }
+    } catch {
+      // best-effort
+    }
+    renamed++;
+  }
+
+  return { renamed, visited, backupDir: backupRoot };
+}
+
+// ── v3 identity rollback ──────────────────────────────────────────────────
+//
+// Reverses the most recent identity rename for every project that has at
+// least one alias recorded. Picks the most recently appended alias as the
+// target id, renames the project directory back, and pops that entry from
+// the alias list. Idempotent: a project with no aliases is left alone.
+//
+// This is the primary rollback path. The pre-migration backup is a fallback
+// for when alias-based rollback can't proceed (e.g. metadata corruption).
+
+export interface RollbackEntry {
+  currentId: string;
+  restoredId: string;
+  ok: boolean;
+}
+
+export function rollbackProjectIdentities(): RollbackEntry[] {
+  const results: RollbackEntry[] = [];
+  const projectsRoot = join(minkRoot(), "projects");
+  if (!existsSync(projectsRoot)) return results;
+
+  let entries: string[];
+  try {
+    entries = readdirSync(projectsRoot);
+  } catch {
+    return results;
+  }
+
+  for (const currentId of entries) {
+    const projDir = join(projectsRoot, currentId);
+    try {
+      if (!statSync(projDir).isDirectory()) continue;
+    } catch {
+      continue;
+    }
+
+    const meta = getProjectMeta(projDir);
+    if (!meta || !meta.aliases || meta.aliases.length === 0) continue;
+
+    const restoredId = meta.aliases[meta.aliases.length - 1];
+    const targetDir = join(projectsRoot, restoredId);
+
+    if (existsSync(targetDir)) {
+      // Refuse to overwrite an existing directory at the target id.
+      results.push({ currentId, restoredId, ok: false });
+      continue;
+    }
+
+    // Pop the alias before renaming so the resulting on-disk metadata file
+    // reflects the rolled-back state even if the rename itself succeeds.
+    const remainingAliases = meta.aliases.slice(0, -1);
+    const metaPath = join(projDir, "project-meta.json");
+    try {
+      const raw = safeReadJson(metaPath);
+      if (raw && typeof raw === "object" && !Array.isArray(raw)) {
+        const obj = raw as Record<string, unknown>;
+        obj.aliases = remainingAliases;
+        atomicWriteJson(metaPath, obj);
+      }
+    } catch {
+      // best-effort; rollback continues
+    }
+
+    const moved =
+      gitSafe(`mv "${projDir}" "${targetDir}"`) !== null ||
+      (() => {
+        try {
+          renameSync(projDir, targetDir);
+          return true;
+        } catch {
+          return false;
+        }
+      })();
+
+    results.push({ currentId, restoredId, ok: moved });
+  }
+  return results;
+}
+
 export interface MigrateResult {
   ranMigration: boolean;
   fromVersion: number;
@@ -221,13 +533,21 @@ export interface MigrateResult {
 // 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.
+// (interrupted by the budget cap) may have written the latest version 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. The v3 identity step
+// also runs whenever projects.identity=git-remote so a user who flips the
+// flag after the version has already stamped to 3 still gets their projects
+// migrated.
 export function migrateSyncLayout(): MigrateResult {
   const fromVersion = readSyncVersion();
   const pending = listProjectsNeedingMigration();
-  if (fromVersion >= MINK_SYNC_VERSION && pending.length === 0) {
+  const identityMode = resolveConfigValue("projects.identity").value;
+  if (
+    fromVersion >= MINK_SYNC_VERSION &&
+    pending.length === 0 &&
+    identityMode !== "git-remote"
+  ) {
     return {
       ranMigration: false,
       fromVersion,
@@ -288,6 +608,16 @@ 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 };
+    try {
+      identity = migrateProjectIdentities(deviceId);
+    } catch {
+      // best-effort; never block the rest of migration
+    }
+
     // 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.
@@ -295,12 +625,16 @@ export function migrateSyncLayout(): MigrateResult {
       writeSyncVersion(MINK_SYNC_VERSION);
     }
 
-    if (isSyncInitialized() && processed > 0) {
+    if (isSyncInitialized() && (processed > 0 || identity.renamed > 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`;
       gitSafe(
-        `commit -m "mink: migrate sync layout v${fromVersion} -> v${MINK_SYNC_VERSION} (device ${deviceId.slice(0, 8)}, ${processed} projects)"`
+        `commit -m "mink: migrate sync layout v${fromVersion} -> v${MINK_SYNC_VERSION} (device ${deviceId.slice(0, 8)}, ${summary})"`
       );
     }
 
@@ -318,7 +652,70 @@ export function migrateSyncLayout(): MigrateResult {
   }
 }
 
-export function syncMigrateCommand(): void {
+export function syncMigrateCommand(args: string[] = []): void {
+  const dryRun = args.includes("--dry-run");
+  const rollback = args.includes("--rollback");
+
+  if (rollback && dryRun) {
+    console.error("[mink] --rollback and --dry-run cannot be combined");
+    process.exit(1);
+  }
+
+  if (dryRun) {
+    const plan = planIdentityMigration();
+    if (plan.length === 0) {
+      console.log(
+        "[mink] sync migrate --dry-run: no projects to rename (flag is off or no projects on disk)"
+      );
+      return;
+    }
+    const renames = plan.filter((p) => p.action === "rename");
+    const converged = plan.filter((p) => p.action === "skip-converged");
+    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`
+    );
+    for (const p of renames) {
+      console.log(`  rename: ${p.oldId} → ${p.newId}`);
+    }
+    for (const p of converged) {
+      console.log(`  alias:  ${p.oldId} → ${p.newId} (already on disk)`);
+    }
+    for (const p of skippedNoCwd) {
+      console.log(`  skip:   ${p.oldId} — ${p.reason}`);
+    }
+    return;
+  }
+
+  if (rollback) {
+    const results = rollbackProjectIdentities();
+    if (results.length === 0) {
+      console.log("[mink] sync migrate --rollback: nothing to roll back");
+      return;
+    }
+    const ok = results.filter((r) => r.ok);
+    const failed = results.filter((r) => !r.ok);
+    console.log(
+      `[mink] sync migrate --rollback: ${ok.length} restored, ${failed.length} failed`
+    );
+    for (const r of ok) {
+      console.log(`  restored: ${r.currentId} → ${r.restoredId}`);
+    }
+    for (const r of failed) {
+      console.log(
+        `  failed:   ${r.currentId} → ${r.restoredId} (destination already exists or rename blocked)`
+      );
+    }
+    if (ok.length > 0) {
+      console.log(
+        "\n[mink] tip: set projects.identity=path-derived to prevent the next session-start from re-migrating"
+      );
+    }
+    return;
+  }
+
   const result = migrateSyncLayout();
   if (!result.ranMigration) {
     console.log(`[mink] sync migrate: ${result.message ?? "no-op"}`);

package/src/commands/sync.ts

@@ -52,14 +52,17 @@ export async function sync(args: string[]): Promise<void> {
 
     case "migrate": {
       const { syncMigrateCommand } = await import("./sync-migrate");
-      syncMigrateCommand();
+      syncMigrateCommand(args.slice(1));
       return;
     }
 
     default:
       console.error(`[mink] unknown sync subcommand: ${subcommand}`);
       console.error(
-        "Usage: mink sync [init|status|push|pull|pause|resume|disconnect|reconcile|migrate|merge-driver]"
+        "Usage: mink sync [init|status|push|pull|pause|resume|disconnect|reconcile|merge-driver]"
+      );
+      console.error(
+        "       mink sync migrate [--dry-run|--rollback]"
       );
       process.exit(1);
   }

package/src/core/dashboard-server.ts

@@ -35,7 +35,7 @@ import {
   triggerIngestFile,
 } from "./dashboard-api";
 import { listRegisteredProjects, getProjectMeta } from "./project-registry";
-import { generateProjectId } from "./project-id";
+import { projectIdFor } from "./project-id";
 import { runtimeFile, runtimeServe, runtimeSpawn } from "./runtime";
 import type { StateFileId, StateChangeEvent } from "../types/dashboard";
 import type { RegisteredProject } from "./project-registry";
@@ -154,10 +154,14 @@ function resolveProjectCwd(
 
   // If the requested project matches the currently active project, use it directly
   // (handles startup projects that may not be in the registry yet)
-  if (projectId === generateProjectId(defaultCwd)) return defaultCwd;
+  if (projectId === projectIdFor(defaultCwd)) return defaultCwd;
 
   const projects = listRegisteredProjects();
-  const match = projects.find((p) => p.id === projectId);
+  // Match against primary id first, then walk alias lists so historical
+  // dashboard URLs continue routing after a v3 identity migration.
+  const match =
+    projects.find((p) => p.id === projectId) ??
+    projects.find((p) => p.aliases.includes(projectId));
   if (!match) return null;
 
   return match.cwd;
@@ -170,11 +174,11 @@ function getProjectsList(
   projects: RegisteredProject[];
   activeProjectId: string;
 } {
-  const activeId = generateProjectId(activeCwd);
+  const activeId = projectIdFor(activeCwd);
   const registered = listRegisteredProjects();
 
   // Ensure startup project is always in the list
-  const startupId = generateProjectId(startupCwd);
+  const startupId = projectIdFor(startupCwd);
   const hasStartup = registered.some((p) => p.id === startupId);
   if (!hasStartup) {
     const meta = getProjectMeta(projectDir(startupCwd));
@@ -183,6 +187,8 @@ function getProjectsList(
       cwd: startupCwd,
       name: meta?.name ?? basename(startupCwd),
       version: meta?.version ?? "0.1.0",
+      aliases: meta?.aliases ?? [],
+      pathsByDevice: meta?.pathsByDevice ?? {},
     });
   }
 
@@ -196,6 +202,8 @@ function getProjectsList(
         cwd: activeCwd,
         name: meta?.name ?? basename(activeCwd),
         version: meta?.version ?? "0.1.0",
+        aliases: meta?.aliases ?? [],
+        pathsByDevice: meta?.pathsByDevice ?? {},
       });
     }
   }