@drewpayment/mink 0.10.1 → 0.11.0-beta.2

package/src/core/git-identity.ts

@@ -0,0 +1,120 @@
+import { execSync } from "child_process";
+import { existsSync, realpathSync } from "fs";
+
+const GIT_TIMEOUT_MS = 2_000;
+
+function gitOut(cwd: string, args: string): string | null {
+  if (!existsSync(cwd)) return null;
+  try {
+    return execSync(`git ${args}`, {
+      cwd,
+      timeout: GIT_TIMEOUT_MS,
+      stdio: ["pipe", "pipe", "pipe"],
+    })
+      .toString()
+      .trim();
+  } catch {
+    return null;
+  }
+}
+
+function canonicalCwd(cwd: string): string {
+  try {
+    return realpathSync(cwd);
+  } catch {
+    return cwd;
+  }
+}
+
+export function getRepoRoot(cwd: string): string | null {
+  const root = gitOut(canonicalCwd(cwd), "rev-parse --show-toplevel");
+  return root && root.length > 0 ? root : null;
+}
+
+export function getRepoSubpath(cwd: string): string {
+  const prefix = gitOut(canonicalCwd(cwd), "rev-parse --show-prefix");
+  if (prefix === null) return "";
+  return prefix.replace(/\\/g, "/").replace(/\/+$/, "").replace(/^\/+/, "");
+}
+
+// Resolves the project's primary remote URL. Prefers `origin` when present —
+// otherwise falls back to the alphabetically-first remote so projects with a
+// non-standard remote name still get a stable identity.
+export function getRepoRemote(cwd: string): string | null {
+  const c = canonicalCwd(cwd);
+  const origin = gitOut(c, "config --get remote.origin.url");
+  if (origin && origin.length > 0) return origin;
+
+  const list = gitOut(c, "remote");
+  if (!list) return null;
+  const remotes = list
+    .split("\n")
+    .map((s) => s.trim())
+    .filter((s) => s.length > 0)
+    .sort();
+  if (remotes.length === 0) return null;
+  const url = gitOut(c, `config --get remote.${remotes[0]}.url`);
+  return url && url.length > 0 ? url : null;
+}
+
+// Reduces remote URL forms to a single canonical string so SSH/HTTPS, with or
+// without credentials, with or without `.git`, and with mixed host casing all
+// collapse to one representation per logical repository.
+//
+// Examples that all collapse to `github.com/owner/repo`:
+//   git@github.com:Owner/Repo.git
+//   https://github.com/owner/repo.git
+//   https://user:token@github.com/owner/repo
+//   ssh://git@github.com/owner/repo/
+//
+// Returns the original string only if it cannot be parsed — callers can still
+// treat that as "no usable remote" and fall back to path-derived identity.
+export function normalizeRemoteUrl(url: string): string {
+  if (!url) return "";
+  let s = url.trim();
+  if (s.length === 0) return "";
+
+  // Skip file/local protocol — these aren't shared identities.
+  if (/^(file:|\.\.?\/|\/)/i.test(s)) return "";
+
+  // SSH scp-style: git@host:owner/repo(.git) → ssh://git@host/owner/repo
+  const scp = s.match(/^([^@\s]+)@([^:\s]+):(.+)$/);
+  if (scp) {
+    s = `ssh://${scp[1]}@${scp[2]}/${scp[3]}`;
+  }
+
+  // Strip leading scheme so we can normalize the rest uniformly.
+  s = s.replace(/^[a-z][a-z0-9+.-]*:\/\//i, "");
+
+  // Strip embedded credentials: `user:pass@host/...` → `host/...`
+  s = s.replace(/^[^@/]*@/, "");
+
+  // Strip trailing slash and `.git`
+  s = s.replace(/\/+$/, "").replace(/\.git$/i, "");
+
+  // Lowercase the entire path. Major forges (GitHub, GitLab, Bitbucket) treat
+  // repo names as case-insensitive for URL routing, so two checkouts whose
+  // remotes differ only in casing point at the same logical repo. Users on
+  // case-sensitive self-hosted forges can pin identity with the override file.
+  return s.toLowerCase();
+}
+
+export interface GitIdentityComponents {
+  remote: string;
+  subpath: string;
+}
+
+// Returns the (remote, subpath) pair for `cwd` if it lives inside a git repo
+// with a normalizable remote. Returns null when the directory is not a git
+// repo, has no remote, or the remote URL is a local/file path. Callers should
+// fall back to path-derived identity in those cases.
+export function deriveGitIdentity(cwd: string): GitIdentityComponents | null {
+  const root = getRepoRoot(cwd);
+  if (!root) return null;
+  const remoteRaw = getRepoRemote(cwd);
+  if (!remoteRaw) return null;
+  const remote = normalizeRemoteUrl(remoteRaw);
+  if (!remote) return null;
+  const subpath = getRepoSubpath(cwd);
+  return { remote, subpath };
+}

package/src/core/paths.ts

@@ -1,6 +1,7 @@
 import { join } from "path";
+import { existsSync } from "fs";
 import { homedir } from "os";
-import { generateProjectId } from "./project-id";
+import { projectIdFor } from "./project-id";
 
 // Resolved per-call so tests can override via MINK_ROOT_OVERRIDE without
 // reloading modules. Production callers get the default homedir/.mink path.
@@ -19,9 +20,24 @@ export function minkRoot(): string {
   return MINK_ROOT;
 }
 
+// Locates the on-disk project state directory for `cwd`. Walks the alias list
+// when the primary identifier's directory does not exist, so historical
+// references (notes, dashboard URLs) keep resolving after a v3 migration
+// renames the project directory.
 export function projectDir(cwd: string): string {
-  const id = generateProjectId(cwd);
-  return join(minkRoot(), "projects", id);
+  const id = projectIdFor(cwd);
+  const primary = join(minkRoot(), "projects", id);
+  if (existsSync(primary)) return primary;
+  // Lazy require: project-registry imports paths, so a top-level import would
+  // create a cycle. Only walk aliases on a cold miss.
+  try {
+    const { findProjectDirByIdOrAlias } = require("./project-registry");
+    const aliased = findProjectDirByIdOrAlias(id);
+    if (aliased) return aliased;
+  } catch {
+    // best-effort
+  }
+  return primary;
 }
 
 export function sessionPath(cwd: string): string {

package/src/core/project-id.ts

@@ -1,5 +1,7 @@
 import { createHash } from "crypto";
-import { basename } from "path";
+import { basename, join } from "path";
+import { existsSync, readFileSync } from "fs";
+import { deriveGitIdentity, getRepoRoot } from "./git-identity";
 
 function slugify(name: string): string {
   return name
@@ -8,12 +10,155 @@ function slugify(name: string): string {
     .replace(/^-|-$/g, "");
 }
 
+function shortHash(input: string): string {
+  return createHash("sha256").update(input).digest("hex").slice(0, 6);
+}
+
+// Legacy identity: hash of the absolute path. Retained for two reasons:
+// 1) The path-derived fallback tier of the new resolver returns this verbatim
+//    so non-git directories continue to behave exactly as before.
+// 2) The v2→v3 migration computes the prior identifier with this function so
+//    it can locate and rename the old per-project state directory.
 export function generateProjectId(absolutePath: string): string {
   const normalized = absolutePath.replace(/\/+$/, "");
   const slug = slugify(basename(normalized));
-  const hash = createHash("sha256")
-    .update(normalized)
-    .digest("hex")
-    .slice(0, 6);
+  const hash = shortHash(normalized);
   return `${slug}-${hash}`;
 }
+
+// ── Stable-identity resolver ──────────────────────────────────────────────
+//
+// Three-tier priority order:
+//   1. Explicit override file inside the user's repo (.mink/project.json)
+//   2. Git-derived: normalized remote URL + repo-root-relative subpath
+//   3. Path-derived fallback (legacy generateProjectId)
+//
+// Gated by the `projects.identity` config key. When the value is
+// `path-derived` (default during rollout) the resolver short-circuits to the
+// legacy behavior so existing users see no change until they opt in.
+
+export type IdentitySource = "override" | "git-remote" | "path-derived";
+
+export interface ProjectIdentity {
+  id: string;
+  source: IdentitySource;
+}
+
+const IDENTIFIER_PATTERN = /^[a-z0-9][a-z0-9._-]{0,127}$/;
+const OVERRIDE_RELATIVE_PATH = ".mink/project.json";
+
+export function validateProjectIdentifier(id: unknown): id is string {
+  return typeof id === "string" && IDENTIFIER_PATTERN.test(id);
+}
+
+// Reads .mink/project.json from the repo containing `cwd` (or `cwd` itself if
+// it is not inside a git repo). Returns the validated identifier, or null when
+// the file is missing, unreadable, malformed, or declares an invalid identifier.
+//
+// Malformed overrides are reported once to stderr so the user notices when
+// their pin file has been ignored — silent fall-through would let typos linger.
+export function readProjectOverride(cwd: string): string | null {
+  const root = getRepoRoot(cwd) ?? cwd;
+  const overridePath = join(root, OVERRIDE_RELATIVE_PATH);
+  if (!existsSync(overridePath)) return null;
+
+  let raw: string;
+  try {
+    raw = readFileSync(overridePath, "utf-8");
+  } catch {
+    return null;
+  }
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    warnInvalidOverride(overridePath, "file is not valid JSON");
+    return null;
+  }
+
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    warnInvalidOverride(overridePath, "expected a JSON object");
+    return null;
+  }
+
+  const id = (parsed as Record<string, unknown>).projectId;
+  if (id === undefined) return null;
+  if (!validateProjectIdentifier(id)) {
+    warnInvalidOverride(
+      overridePath,
+      "projectId must start with a letter or digit, contain only [a-z0-9._-], and be 1–128 characters"
+    );
+    return null;
+  }
+  return id;
+}
+
+const warnedOverrides = new Set<string>();
+function warnInvalidOverride(path: string, reason: string): void {
+  if (warnedOverrides.has(path)) return;
+  warnedOverrides.add(path);
+  console.warn(`[mink] ignoring ${path}: ${reason}`);
+}
+
+// Returns the git-derived identifier for `cwd` when it lives inside a git repo
+// with a normalizable remote. Returns null otherwise so the caller can fall
+// through to the path-derived tier.
+function gitDerivedIdentity(cwd: string): string | null {
+  const components = deriveGitIdentity(cwd);
+  if (!components) return null;
+  // Slug derives from the normalized remote or subpath — never from the local
+  // checkout's directory name — so two clones at differently-named paths
+  // produce the same identifier.
+  const remoteLeaf = components.remote.split("/").filter((p) => p).pop();
+  const slugSource = components.subpath
+    ? components.subpath.split("/").pop()!
+    : remoteLeaf ?? "project";
+  const slug = slugify(slugSource);
+  const hash = shortHash(`git:${components.remote}:${components.subpath}`);
+  return `${slug}-${hash}`;
+}
+
+function readIdentityMode(): "path-derived" | "git-remote" {
+  const envOverride = process.env.MINK_PROJECTS_IDENTITY;
+  if (envOverride === "git-remote" || envOverride === "path-derived") {
+    return envOverride;
+  }
+  try {
+    // Lazy require to avoid a cycle: global-config imports types/config which
+    // is small; project-id is imported very widely.
+    const { resolveConfigValue } = require("./global-config");
+    const v = resolveConfigValue("projects.identity").value;
+    if (v === "git-remote") return "git-remote";
+  } catch {
+    // fall through
+  }
+  return "path-derived";
+}
+
+// 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" };
+  }
+
+  const override = readProjectOverride(cwd);
+  if (override) return { id: override, source: "override" };
+
+  const git = gitDerivedIdentity(cwd);
+  if (git) return { id: git, source: "git-remote" };
+
+  return { id: generateProjectId(cwd), source: "path-derived" };
+}
+
+export function projectIdFor(cwd: string): string {
+  return resolveProjectIdentity(cwd).id;
+}

package/src/core/project-registry.ts

@@ -1,13 +1,27 @@
 import { readdirSync, existsSync } from "fs";
 import { join } from "path";
 import { minkRoot } from "./paths";
-import { safeReadJson } from "./fs-utils";
+import { safeReadJson, atomicWriteJson } from "./fs-utils";
+
+// ── Project metadata ──────────────────────────────────────────────────────
+//
+// `project-meta.json` records who/what/when about a project's state directory.
+// The schema evolved across sync versions:
+//
+//   v1/v2: { cwd, name, initTimestamp, version, projectType? }
+//   v3:    adds { aliases: string[], pathsByDevice: Record<deviceId, cwd> }
+//
+// `cwd` is preserved on disk for forward-compat with older mink versions that
+// downgrade after a v3 migration — they continue to read it. New code prefers
+// `pathsByDevice[deviceId]` and treats `cwd` as a single-device fallback.
 
 export interface ProjectMeta {
   cwd: string;
   name: string;
   initTimestamp: string;
   version: string;
+  aliases?: string[];
+  pathsByDevice?: Record<string, string>;
 }
 
 export interface RegisteredProject {
@@ -15,30 +29,97 @@ export interface RegisteredProject {
   cwd: string;
   name: string;
   version: string;
+  aliases: string[];
+  pathsByDevice: Record<string, string>;
+}
+
+function projectMetaFilePath(projDir: string): string {
+  return join(projDir, "project-meta.json");
 }
 
 export function getProjectMeta(projDir: string): ProjectMeta | null {
-  const metaPath = join(projDir, "project-meta.json");
-  const raw = safeReadJson(metaPath);
-  if (
-    raw === null ||
-    typeof raw !== "object" ||
-    Array.isArray(raw)
-  ) {
-    return null;
-  }
+  const raw = safeReadJson(projectMetaFilePath(projDir));
+  if (raw === null || typeof raw !== "object" || Array.isArray(raw)) return null;
   const obj = raw as Record<string, unknown>;
-  if (typeof obj.cwd !== "string" || typeof obj.name !== "string") {
-    return null;
-  }
+  if (typeof obj.cwd !== "string" || typeof obj.name !== "string") return null;
+
+  const aliases = Array.isArray(obj.aliases)
+    ? (obj.aliases as unknown[]).filter((s): s is string => typeof s === "string")
+    : undefined;
+
+  const pathsByDevice =
+    obj.pathsByDevice &&
+    typeof obj.pathsByDevice === "object" &&
+    !Array.isArray(obj.pathsByDevice)
+      ? Object.fromEntries(
+          Object.entries(obj.pathsByDevice as Record<string, unknown>).filter(
+            ([, v]) => typeof v === "string"
+          ) as [string, string][]
+        )
+      : undefined;
+
   return {
     cwd: obj.cwd as string,
     name: obj.name as string,
     initTimestamp: (obj.initTimestamp as string) ?? "",
     version: (obj.version as string) ?? "0.1.0",
+    aliases,
+    pathsByDevice,
   };
 }
 
+// Idempotently records `aliasId` on the project at `projDir`. Preserves the
+// existing alias list, deduplicates, and preserves any unknown fields on the
+// metadata record so a future-version downgrade doesn't lose data.
+export function addProjectAlias(projDir: string, aliasId: string): boolean {
+  const path = projectMetaFilePath(projDir);
+  const raw = safeReadJson(path);
+  if (raw === null || typeof raw !== "object" || Array.isArray(raw)) return false;
+  const obj = raw as Record<string, unknown>;
+  const existing = Array.isArray(obj.aliases)
+    ? (obj.aliases as unknown[]).filter((s): s is string => typeof s === "string")
+    : [];
+  if (existing.includes(aliasId)) return false;
+  obj.aliases = [...existing, aliasId];
+  atomicWriteJson(path, obj);
+  return true;
+}
+
+// Writes the working-copy path for the given device into the per-device map.
+// Reads the existing map (or seeds it from the legacy singular `cwd` field if
+// no map exists yet) and writes the merged result back. Preserves unknown fields.
+export function setProjectPathForDevice(
+  projDir: string,
+  deviceId: string,
+  cwd: string
+): void {
+  const path = projectMetaFilePath(projDir);
+  const raw = safeReadJson(path);
+  if (raw === null || typeof raw !== "object" || Array.isArray(raw)) return;
+  const obj = raw as Record<string, unknown>;
+  const existing =
+    obj.pathsByDevice &&
+    typeof obj.pathsByDevice === "object" &&
+    !Array.isArray(obj.pathsByDevice)
+      ? { ...(obj.pathsByDevice as Record<string, string>) }
+      : {};
+  // Seed the map from the legacy singular cwd so the first device-keyed write
+  // doesn't drop the prior single-device path on the floor.
+  if (
+    Object.keys(existing).length === 0 &&
+    typeof obj.cwd === "string" &&
+    obj.cwd !== cwd
+  ) {
+    existing[deviceId] = obj.cwd;
+  }
+  existing[deviceId] = cwd;
+  obj.pathsByDevice = existing;
+  // Keep `cwd` in sync as the local-machine fallback so older versions still
+  // read a meaningful value after a downgrade.
+  obj.cwd = cwd;
+  atomicWriteJson(path, obj);
+}
+
 export function listRegisteredProjects(): RegisteredProject[] {
   const projectsDir = join(minkRoot(), "projects");
   if (!existsSync(projectsDir)) return [];
@@ -56,9 +137,37 @@ export function listRegisteredProjects(): RegisteredProject[] {
         cwd: meta.cwd,
         name: meta.name,
         version: meta.version,
+        aliases: meta.aliases ?? [],
+        pathsByDevice: meta.pathsByDevice ?? {},
       });
     }
   }
 
   return projects;
 }
+
+// Scans every project directory for one whose on-disk name or alias list matches
+// `id`. Returns the on-disk project directory or null. Used by paths.ts to
+// tolerate historical references after migration renames the project's
+// directory.
+export function findProjectDirByIdOrAlias(id: string): string | null {
+  const projectsDir = join(minkRoot(), "projects");
+  if (!existsSync(projectsDir)) return null;
+
+  const primary = join(projectsDir, id);
+  if (existsSync(primary)) return primary;
+
+  let entries: string[];
+  try {
+    entries = readdirSync(projectsDir);
+  } catch {
+    return null;
+  }
+
+  for (const name of entries) {
+    const projDir = join(projectsDir, name);
+    const meta = getProjectMeta(projDir);
+    if (meta?.aliases?.includes(id)) return projDir;
+  }
+  return null;
+}

package/src/core/sync.ts

@@ -15,7 +15,13 @@ const FETCH_TIMEOUT = 15_000;
 // Sync layout version. Bumped when the on-disk shape of `~/.mink/` changes in
 // a way that older devices cannot read. Migration runs on first session-start
 // after upgrade when readSyncVersion() < MINK_SYNC_VERSION.
-export const MINK_SYNC_VERSION = 2;
+//
+// v1 → v2: per-device shards under projects/<id>/state/<deviceId>/
+// v2 → v3: stable identity — adds aliases[] and pathsByDevice{} on project-meta;
+//          when projects.identity=git-remote, renames per-project directories
+//          from path-derived IDs to git-derived IDs and records prior ID as
+//          alias. Migration is a no-op when the flag is off.
+export const MINK_SYNC_VERSION = 3;
 
 export function readSyncVersion(): number {
   try {

package/src/types/config.ts

@@ -17,6 +17,7 @@ export interface GlobalConfig {
   "cli.auto-update"?: string;
   "cli.auto-update-schedule"?: string;
   "cli.auto-update-package-manager"?: string;
+  "projects.identity"?: string;
 }
 
 export type ConfigKey = keyof GlobalConfig & string;
@@ -170,6 +171,14 @@ export const CONFIG_KEYS: ConfigKeyMeta[] = [
     description: "Force a package manager (auto|npm|bun) for self-upgrade installs",
     scope: "local",
   },
+  {
+    key: "projects.identity",
+    default: "path-derived",
+    envVar: "MINK_PROJECTS_IDENTITY",
+    description:
+      "Project identity strategy: path-derived (legacy) or git-remote (stable across machines)",
+    scope: "shared",
+  },
 ];
 
 const VALID_KEYS = new Set<string>(CONFIG_KEYS.map((k) => k.key));