@drewpayment/mink 0.10.0 → 0.11.0-beta.1

package/src/commands/wiki.ts

@@ -14,7 +14,11 @@ import {
 import { atomicWriteJson } from "../core/fs-utils";
 import { setConfigValue } from "../core/global-config";
 import { seedTemplates } from "../core/vault-templates";
-import { rebuildVaultIndex, loadVaultIndex } from "../core/note-index";
+import {
+  rebuildVaultIndex,
+  loadVaultIndex,
+  vaultIndexStaleness,
+} from "../core/note-index";
 import { updateMasterIndex } from "../core/note-linker";
 import type { VaultManifest, NoteCategory } from "../types/note";
 
@@ -32,6 +36,7 @@ export async function wiki(
       wikiStatus();
       break;
     case "rebuild-index":
+    case "scan":
       wikiRebuildIndex();
       break;
     case "organize":
@@ -51,7 +56,8 @@ export async function wiki(
       console.log();
       console.log("  init                Initialize the notes/wiki vault");
       console.log("  status              Show vault statistics");
-      console.log("  rebuild-index       Full rescan and reindex of vault");
+      console.log("  rebuild-index       Full rescan and reindex of vault (alias: scan)");
+      console.log("  scan                Alias for rebuild-index");
       console.log("  organize            List inbox notes needing categorization");
       console.log("  link <path> [name]  Symlink external notes into the vault");
       console.log("  unlink <name>       Remove a symlinked directory from the vault");
@@ -174,6 +180,13 @@ function wikiStatus(): void {
   }
 
   const vaultPath = resolveVaultPath();
+  const staleness = vaultIndexStaleness();
+  if (staleness.isStale) {
+    console.log(
+      `[mink] vault index is stale (${staleness.reason}) — rebuilding...`
+    );
+    rebuildVaultIndex();
+  }
   const index = loadVaultIndex();
 
   const categoryCounts: Record<string, number> = {
@@ -200,7 +213,10 @@ function wikiStatus(): void {
   }
   console.log();
   console.log(
-    `  last indexed: ${index.lastScanTimestamp || "never"}`
+    `  last full scan: ${index.lastFullScanTimestamp || "never"}`
+  );
+  console.log(
+    `  last update:    ${index.lastScanTimestamp || "never"}`
   );
 
   const links = listLinks();

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 ?? {},
       });
     }
   }

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/note-index.ts

@@ -7,6 +7,7 @@ import type { VaultIndex, VaultIndexEntry, NoteCategory } from "../types/note";
 export function createEmptyVaultIndex(): VaultIndex {
   return {
     lastScanTimestamp: "",
+    lastFullScanTimestamp: "",
     totalNotes: 0,
     entries: {},
   };
@@ -182,7 +183,9 @@ export function rebuildVaultIndex(): VaultIndex {
     }
   }
 
-  index.lastScanTimestamp = new Date().toISOString();
+  const now = new Date().toISOString();
+  index.lastScanTimestamp = now;
+  index.lastFullScanTimestamp = now;
   saveVaultIndex(index);
   return index;
 }
@@ -219,6 +222,52 @@ export function getRecentNotes(n: number): VaultIndexEntry[] {
     .slice(0, n);
 }
 
+export interface VaultStaleness {
+  isStale: boolean;
+  reason: string | null;
+  diskCount: number;
+  indexCount: number;
+  lastFullScan: string | null;
+}
+
+export function vaultIndexStaleness(): VaultStaleness {
+  const index = loadVaultIndex();
+  const root = resolveVaultPath();
+  const diskCount = collectAllMarkdown(root).length;
+  const indexCount = Object.keys(index.entries).length;
+  const lastFullScan = index.lastFullScanTimestamp || null;
+
+  if (!lastFullScan) {
+    return {
+      isStale: true,
+      reason: "no full scan on record",
+      diskCount,
+      indexCount,
+      lastFullScan: null,
+    };
+  }
+
+  const delta = Math.abs(diskCount - indexCount);
+  const threshold = Math.max(5, Math.floor(diskCount * 0.05));
+  if (delta >= threshold) {
+    return {
+      isStale: true,
+      reason: `${diskCount} files on disk but ${indexCount} in index`,
+      diskCount,
+      indexCount,
+      lastFullScan,
+    };
+  }
+
+  return {
+    isStale: false,
+    reason: null,
+    diskCount,
+    indexCount,
+    lastFullScan,
+  };
+}
+
 interface ScannedMarkdown {
   absolutePath: string;
   relativePath: string;

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,147 @@ 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";
+}
+
+export function resolveProjectIdentity(cwd: string): ProjectIdentity {
+  const mode = 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;
+}