@evo-dev/core 0.0.1-alpha.2 → 0.0.1-alpha.20

package/src/projects/index.ts

@@ -0,0 +1,934 @@
+import { lstat, readFile, readdir, realpath, stat } from "node:fs/promises";
+import { basename, dirname, isAbsolute, join, parse } from "node:path";
+import { resolveEvoDevPaths } from "../config/paths.ts";
+import { resolvePathProjectLogKey, resolveProjectLogIdentity } from "../runtime-logs/index.ts";
+import {
+  isFileExistsError,
+  isNotFoundError,
+  normalizeTimestamp,
+  sanitizeStorageId,
+  sha256Short,
+  writeJsonFile,
+} from "../utils/index.ts";
+
+export type ProjectWorkspaceKind = "git" | "directory";
+export type ProjectDiscoveryTarget = "claude" | "codex";
+
+export interface ResolvedProjectWorkspace {
+  projectKey: string;
+  workspaceKey: string;
+  displayName: string;
+  projectRoot: string;
+  workspaceRoot: string;
+  workspaceKind: ProjectWorkspaceKind;
+  gitCommonDir: string | null;
+  linkedWorktree: boolean;
+  cwd: string;
+}
+
+export interface DiscoveredProjectRecordV1 {
+  schemaVersion: 1;
+  kind: "discovered-project";
+  projectKey: string;
+  displayName: string;
+  workspaceRoot: string;
+  lastCwd: string;
+  workspaceKind: ProjectWorkspaceKind;
+  sourceTargets: ProjectDiscoveryTarget[];
+  lastSessionKey: string | null;
+  firstSeenAt: string;
+  lastSeenAt: string;
+  localOnly: true;
+  sourceContentStored: false;
+}
+
+export interface RegisteredProjectRecordV1 {
+  schemaVersion: 1;
+  kind: "registered-project";
+  projectKey: string;
+  displayName: string;
+  workspaceRoot: string;
+  workspaceKind: ProjectWorkspaceKind;
+  registeredAt: string;
+  lastSeenAt: string;
+  localOnly: true;
+  sourceContentStored: false;
+}
+
+export interface ProjectWorkspaceRecordV1 {
+  schemaVersion: 1;
+  kind: "project-workspace";
+  workspaceKey: string;
+  projectKey: string;
+  displayName: string;
+  workspaceRoot: string;
+  workspaceKind: ProjectWorkspaceKind;
+  gitCommonDir: string | null;
+  sourceTargets: ProjectDiscoveryTarget[];
+  firstSeenAt: string;
+  lastSeenAt: string;
+  localOnly: true;
+  sourceContentStored: false;
+}
+
+export interface ProjectWorkspaceSummary extends ProjectWorkspaceRecordV1 {
+  available: boolean;
+}
+
+export interface ProjectAliasRecordV1 {
+  schemaVersion: 1;
+  kind: "project-alias";
+  aliasProjectKey: string;
+  canonicalProjectKey: string;
+  workspaceRoot: string;
+  createdAt: string;
+  updatedAt: string;
+  localOnly: true;
+  sourceContentStored: false;
+}
+
+export type ProjectAliasMap = Record<string, string>;
+
+export class ProjectRegistrationError extends Error {
+  readonly code: "invalid" | "not-found" | "conflict";
+
+  constructor(code: "invalid" | "not-found" | "conflict", message: string) {
+    super(message);
+    this.name = "ProjectRegistrationError";
+    this.code = code;
+  }
+}
+
+export function resolveProjectRegistryPaths(homeDir: string): {
+  discoveredDir: string;
+  registeredDir: string;
+  workspaceDir: string;
+  aliasDir: string;
+  discoveredPath: (projectKey: string) => string;
+  registeredPath: (projectKey: string) => string;
+  workspacePath: (workspaceKey: string) => string;
+  aliasPath: (aliasProjectKey: string) => string;
+} {
+  const paths = resolveEvoDevPaths(homeDir);
+  const discoveredDir = join(paths.stateDir, "projects", "discovered");
+  const registeredDir = join(paths.rootDir, "projects");
+  const workspaceDir = join(paths.stateDir, "projects", "workspaces");
+  const aliasDir = join(paths.stateDir, "projects", "aliases");
+  return {
+    discoveredDir,
+    registeredDir,
+    workspaceDir,
+    aliasDir,
+    discoveredPath: (projectKey) => join(discoveredDir, `${projectKey}.json`),
+    registeredPath: (projectKey) => join(registeredDir, projectKey, "workspace.json"),
+    workspacePath: (workspaceKey) => join(workspaceDir, `${workspaceKey}.json`),
+    aliasPath: (aliasProjectKey) => join(aliasDir, `${aliasProjectKey}.json`),
+  };
+}
+
+export async function resolveProjectWorkspaceFromCwd(input: {
+  homeDir: string;
+  cwd: string;
+}): Promise<ResolvedProjectWorkspace | null> {
+  if (!isAbsolute(input.cwd)) return null;
+
+  let cwd: string;
+  try {
+    const info = await stat(input.cwd);
+    if (!info.isDirectory()) return null;
+    cwd = await realpath(input.cwd);
+  } catch (error) {
+    if (isNotFoundError(error)) return null;
+    throw error;
+  }
+
+  const gitRoot = await findNearestGitRoot(cwd);
+  const workspaceRoot = gitRoot ?? cwd;
+  const identity = resolveProjectLogIdentity(input.homeDir, workspaceRoot);
+  return {
+    projectKey: sanitizeStorageId(identity.projectKey, "project"),
+    workspaceKey: sanitizeStorageId(identity.workspaceKey, "workspace"),
+    displayName: basename(identity.projectRoot) || parse(identity.projectRoot).root,
+    projectRoot: identity.projectRoot,
+    workspaceRoot,
+    workspaceKind: gitRoot === null ? "directory" : "git",
+    gitCommonDir: identity.gitCommonDir,
+    linkedWorktree: identity.linkedWorktree,
+    cwd,
+  };
+}
+
+export async function recordDiscoveredProject(input: {
+  homeDir: string;
+  cwd: string;
+  target: ProjectDiscoveryTarget;
+  sessionKey?: string | null;
+  now?: Date | string;
+}): Promise<{ record: DiscoveredProjectRecordV1; path: string } | null> {
+  const workspace = await resolveProjectWorkspaceFromCwd(input);
+  if (workspace === null) return null;
+
+  const now = normalizeTimestamp(input.now);
+  const paths = resolveProjectRegistryPaths(input.homeDir);
+  const path = paths.discoveredPath(workspace.projectKey);
+  const existing = await readDiscoveredProject(path);
+  await writeProjectWorkspaceRecord({
+    paths,
+    workspace,
+    target: input.target,
+    now,
+  });
+  if (workspace.workspaceKey !== workspace.projectKey) {
+    await writeProjectAliasRecord({
+      paths,
+      aliasProjectKey: workspace.workspaceKey,
+      canonicalProjectKey: workspace.projectKey,
+      workspaceRoot: workspace.workspaceRoot,
+      now,
+    });
+  }
+  const record: DiscoveredProjectRecordV1 = {
+    schemaVersion: 1,
+    kind: "discovered-project",
+    projectKey: workspace.projectKey,
+    displayName: workspace.displayName,
+    workspaceRoot: workspace.projectRoot,
+    lastCwd: workspace.cwd,
+    workspaceKind: workspace.workspaceKind,
+    sourceTargets: mergeTargets(existing?.sourceTargets ?? [], [input.target]),
+    lastSessionKey: normalizeSessionKey(input.sessionKey ?? existing?.lastSessionKey ?? null),
+    firstSeenAt: existing?.firstSeenAt ?? now,
+    lastSeenAt: now,
+    localOnly: true,
+    sourceContentStored: false,
+  };
+  await writeJsonFile(path, record);
+  return { record, path };
+}
+
+export async function listDiscoveredProjects(input: {
+  homeDir: string;
+}): Promise<DiscoveredProjectRecordV1[]> {
+  const paths = resolveProjectRegistryPaths(input.homeDir);
+  const records = new Map<string, DiscoveredProjectRecordV1>();
+  const aliases = await listProjectAliases(input);
+
+  for (const path of await listJsonFilePaths(paths.discoveredDir)) {
+    const record = await readDiscoveredProject(path);
+    if (record !== null) {
+      mergeDiscoveredRecord(
+        records,
+        await canonicalizeDiscoveredRecord(input.homeDir, record, aliases),
+      );
+    }
+  }
+
+  for (const binding of await listLegacyHookBindings(input.homeDir)) {
+    if (binding.cwd === null) continue;
+    const workspace = await resolveProjectWorkspaceFromCwd({
+      homeDir: input.homeDir,
+      cwd: binding.cwd,
+    });
+    if (workspace === null) continue;
+    mergeDiscoveredRecord(records, {
+      schemaVersion: 1,
+      kind: "discovered-project",
+      projectKey: workspace.projectKey,
+      displayName: workspace.displayName,
+      workspaceRoot: workspace.projectRoot,
+      lastCwd: workspace.cwd,
+      workspaceKind: workspace.workspaceKind,
+      sourceTargets: [binding.target],
+      lastSessionKey: normalizeSessionKey(binding.sessionKey),
+      firstSeenAt: binding.updatedAt,
+      lastSeenAt: binding.updatedAt,
+      localOnly: true,
+      sourceContentStored: false,
+    });
+  }
+
+  return [...records.values()].sort(
+    (left, right) =>
+      right.lastSeenAt.localeCompare(left.lastSeenAt) ||
+      left.projectKey.localeCompare(right.projectKey),
+  );
+}
+
+export async function listRegisteredProjects(input: {
+  homeDir: string;
+}): Promise<RegisteredProjectRecordV1[]> {
+  const { registeredDir } = resolveProjectRegistryPaths(input.homeDir);
+  const aliases = await listProjectAliases(input);
+  const records = new Map<string, RegisteredProjectRecordV1>();
+  for (const projectKey of await listDirectoryNames(registeredDir)) {
+    const record = await readRegisteredProject(join(registeredDir, projectKey, "workspace.json"));
+    if (record === null || record.projectKey !== projectKey) continue;
+    mergeRegisteredRecord(
+      records,
+      await canonicalizeRegisteredRecord(input.homeDir, record, aliases),
+    );
+  }
+  return [...records.values()].sort(
+    (left, right) =>
+      right.lastSeenAt.localeCompare(left.lastSeenAt) ||
+      left.projectKey.localeCompare(right.projectKey),
+  );
+}
+
+export async function listProjectAliases(input: {
+  homeDir: string;
+}): Promise<ProjectAliasMap> {
+  const paths = resolveProjectRegistryPaths(input.homeDir);
+  const aliases: ProjectAliasMap = {};
+  for (const path of await listJsonFilePaths(paths.aliasDir)) {
+    const record = await readProjectAlias(path);
+    if (record !== null) aliases[record.aliasProjectKey] = record.canonicalProjectKey;
+  }
+
+  for (const path of await listJsonFilePaths(paths.discoveredDir)) {
+    const record = await readDiscoveredProject(path);
+    if (record !== null) {
+      await collectAvailableProjectAlias(input.homeDir, record, aliases);
+    }
+  }
+  for (const projectKey of await listDirectoryNames(paths.registeredDir)) {
+    const record = await readRegisteredProject(
+      join(paths.registeredDir, projectKey, "workspace.json"),
+    );
+    if (record !== null) {
+      await collectAvailableProjectAlias(input.homeDir, record, aliases);
+    }
+  }
+  return normalizeProjectAliases(aliases);
+}
+
+export function canonicalizeProjectKey(projectKey: string, aliases: ProjectAliasMap): string {
+  let current = projectKey;
+  const seen = new Set<string>();
+  while (!seen.has(current)) {
+    seen.add(current);
+    const next = aliases[current];
+    if (next === undefined || next === current) return current;
+    current = next;
+  }
+  return projectKey;
+}
+
+export async function listEquivalentProjectKeys(input: {
+  homeDir: string;
+  projectKey: string;
+}): Promise<string[]> {
+  const aliases = await listProjectAliases({ homeDir: input.homeDir });
+  const canonical = canonicalizeProjectKey(input.projectKey, aliases);
+  return [
+    ...new Set([
+      canonical,
+      input.projectKey,
+      ...Object.keys(aliases).filter(
+        (alias) => canonicalizeProjectKey(alias, aliases) === canonical,
+      ),
+    ]),
+  ].sort();
+}
+
+export async function listProjectWorkspaces(input: {
+  homeDir: string;
+}): Promise<ProjectWorkspaceSummary[]> {
+  const paths = resolveProjectRegistryPaths(input.homeDir);
+  const aliases = await listProjectAliases(input);
+  const records = new Map<string, ProjectWorkspaceSummary>();
+
+  for (const path of await listJsonFilePaths(paths.workspaceDir)) {
+    const record = await readProjectWorkspace(path);
+    if (record !== null) {
+      mergeProjectWorkspaceSummary(
+        records,
+        await summarizeProjectWorkspace(input.homeDir, record, aliases),
+      );
+    }
+  }
+  for (const path of await listJsonFilePaths(paths.discoveredDir)) {
+    const record = await readDiscoveredProject(path);
+    if (record !== null) {
+      mergeProjectWorkspaceSummary(
+        records,
+        await summarizeLegacyWorkspace(input.homeDir, record, aliases),
+      );
+    }
+  }
+  for (const projectKey of await listDirectoryNames(paths.registeredDir)) {
+    const record = await readRegisteredProject(
+      join(paths.registeredDir, projectKey, "workspace.json"),
+    );
+    if (record !== null) {
+      mergeProjectWorkspaceSummary(
+        records,
+        await summarizeLegacyWorkspace(input.homeDir, record, aliases),
+      );
+    }
+  }
+
+  return [...records.values()].sort(
+    (left, right) =>
+      left.projectKey.localeCompare(right.projectKey) ||
+      Number(right.available) - Number(left.available) ||
+      right.lastSeenAt.localeCompare(left.lastSeenAt) ||
+      left.workspaceKey.localeCompare(right.workspaceKey),
+  );
+}
+
+export async function registerDiscoveredProject(input: {
+  homeDir: string;
+  projectKey: string;
+  now?: Date | string;
+}): Promise<{ record: RegisteredProjectRecordV1; path: string; changed: boolean }> {
+  assertProjectKey(input.projectKey);
+  const paths = resolveProjectRegistryPaths(input.homeDir);
+  const path = paths.registeredPath(input.projectKey);
+  const existing = await readRegisteredProject(path);
+  if (existing !== null) return { record: existing, path, changed: false };
+
+  const discovered = (await listDiscoveredProjects({ homeDir: input.homeDir })).find(
+    (record) => record.projectKey === input.projectKey,
+  );
+  if (discovered === undefined) {
+    throw new ProjectRegistrationError(
+      "not-found",
+      "The project must be discovered by a local Code Agent session before it can be added.",
+    );
+  }
+
+  const record: RegisteredProjectRecordV1 = {
+    schemaVersion: 1,
+    kind: "registered-project",
+    projectKey: discovered.projectKey,
+    displayName: discovered.displayName,
+    workspaceRoot: discovered.workspaceRoot,
+    workspaceKind: discovered.workspaceKind,
+    registeredAt: normalizeTimestamp(input.now),
+    lastSeenAt: discovered.lastSeenAt,
+    localOnly: true,
+    sourceContentStored: false,
+  };
+  try {
+    await writeJsonFile(path, record, { overwrite: false });
+    return { record, path, changed: true };
+  } catch (error) {
+    if (!isFileExistsError(error)) throw error;
+    const concurrent = await readRegisteredProject(path);
+    if (concurrent !== null) return { record: concurrent, path, changed: false };
+    throw new ProjectRegistrationError("conflict", "The project registration already exists.");
+  }
+}
+
+async function writeProjectWorkspaceRecord(input: {
+  paths: ReturnType<typeof resolveProjectRegistryPaths>;
+  workspace: ResolvedProjectWorkspace;
+  target: ProjectDiscoveryTarget;
+  now: string;
+}): Promise<void> {
+  const path = input.paths.workspacePath(input.workspace.workspaceKey);
+  const existing = await readProjectWorkspace(path);
+  const record: ProjectWorkspaceRecordV1 = {
+    schemaVersion: 1,
+    kind: "project-workspace",
+    workspaceKey: input.workspace.workspaceKey,
+    projectKey: input.workspace.projectKey,
+    displayName:
+      basename(input.workspace.workspaceRoot) || parse(input.workspace.workspaceRoot).root,
+    workspaceRoot: input.workspace.workspaceRoot,
+    workspaceKind: input.workspace.workspaceKind,
+    gitCommonDir: input.workspace.gitCommonDir,
+    sourceTargets: mergeTargets(existing?.sourceTargets ?? [], [input.target]),
+    firstSeenAt: existing?.firstSeenAt ?? input.now,
+    lastSeenAt: input.now,
+    localOnly: true,
+    sourceContentStored: false,
+  };
+  await writeJsonFile(path, record);
+}
+
+async function writeProjectAliasRecord(input: {
+  paths: ReturnType<typeof resolveProjectRegistryPaths>;
+  aliasProjectKey: string;
+  canonicalProjectKey: string;
+  workspaceRoot: string;
+  now: string;
+}): Promise<void> {
+  const path = input.paths.aliasPath(input.aliasProjectKey);
+  const existing = await readProjectAlias(path);
+  const record: ProjectAliasRecordV1 = {
+    schemaVersion: 1,
+    kind: "project-alias",
+    aliasProjectKey: input.aliasProjectKey,
+    canonicalProjectKey: input.canonicalProjectKey,
+    workspaceRoot: input.workspaceRoot,
+    createdAt: existing?.createdAt ?? input.now,
+    updatedAt: input.now,
+    localOnly: true,
+    sourceContentStored: false,
+  };
+  await writeJsonFile(path, record);
+}
+
+async function canonicalizeDiscoveredRecord(
+  homeDir: string,
+  record: DiscoveredProjectRecordV1,
+  aliases: ProjectAliasMap,
+): Promise<DiscoveredProjectRecordV1> {
+  const workspace = await resolveProjectWorkspaceFromCwd({
+    homeDir,
+    cwd: record.workspaceRoot,
+  }).catch(() => null);
+  if (workspace === null) {
+    return {
+      ...record,
+      projectKey: canonicalizeProjectKey(record.projectKey, aliases),
+    };
+  }
+  return {
+    ...record,
+    projectKey: workspace.projectKey,
+    displayName: workspace.displayName,
+    workspaceRoot: workspace.projectRoot,
+    workspaceKind: workspace.workspaceKind,
+  };
+}
+
+async function canonicalizeRegisteredRecord(
+  homeDir: string,
+  record: RegisteredProjectRecordV1,
+  aliases: ProjectAliasMap,
+): Promise<RegisteredProjectRecordV1> {
+  const workspace = await resolveProjectWorkspaceFromCwd({
+    homeDir,
+    cwd: record.workspaceRoot,
+  }).catch(() => null);
+  if (workspace === null) {
+    return {
+      ...record,
+      projectKey: canonicalizeProjectKey(record.projectKey, aliases),
+    };
+  }
+  return {
+    ...record,
+    projectKey: workspace.projectKey,
+    displayName: workspace.displayName,
+    workspaceRoot: workspace.projectRoot,
+    workspaceKind: workspace.workspaceKind,
+  };
+}
+
+async function collectAvailableProjectAlias(
+  homeDir: string,
+  record: Pick<DiscoveredProjectRecordV1, "projectKey" | "workspaceRoot">,
+  aliases: ProjectAliasMap,
+): Promise<void> {
+  const workspace = await resolveProjectWorkspaceFromCwd({
+    homeDir,
+    cwd: record.workspaceRoot,
+  }).catch(() => null);
+  if (workspace === null) return;
+  if (record.projectKey !== workspace.projectKey) {
+    aliases[record.projectKey] = workspace.projectKey;
+  }
+  if (workspace.workspaceKey !== workspace.projectKey) {
+    aliases[workspace.workspaceKey] = workspace.projectKey;
+  }
+}
+
+function normalizeProjectAliases(aliases: ProjectAliasMap): ProjectAliasMap {
+  return Object.fromEntries(
+    Object.keys(aliases)
+      .sort()
+      .flatMap((alias) => {
+        const canonical = canonicalizeProjectKey(alias, aliases);
+        return canonical === alias ? [] : [[alias, canonical]];
+      }),
+  );
+}
+
+async function summarizeProjectWorkspace(
+  homeDir: string,
+  record: ProjectWorkspaceRecordV1,
+  aliases: ProjectAliasMap,
+): Promise<ProjectWorkspaceSummary> {
+  const workspace = await resolveProjectWorkspaceFromCwd({
+    homeDir,
+    cwd: record.workspaceRoot,
+  }).catch(() => null);
+  if (workspace === null) {
+    return {
+      ...record,
+      projectKey: canonicalizeProjectKey(record.projectKey, aliases),
+      available: false,
+    };
+  }
+  return {
+    ...record,
+    workspaceKey: workspace.workspaceKey,
+    projectKey: workspace.projectKey,
+    displayName: basename(workspace.workspaceRoot) || parse(workspace.workspaceRoot).root,
+    workspaceRoot: workspace.workspaceRoot,
+    workspaceKind: workspace.workspaceKind,
+    gitCommonDir: workspace.gitCommonDir,
+    available: true,
+  };
+}
+
+async function summarizeLegacyWorkspace(
+  homeDir: string,
+  record: DiscoveredProjectRecordV1 | RegisteredProjectRecordV1,
+  aliases: ProjectAliasMap,
+): Promise<ProjectWorkspaceSummary> {
+  const workspace = await resolveProjectWorkspaceFromCwd({
+    homeDir,
+    cwd: record.workspaceRoot,
+  }).catch(() => null);
+  const sourceTargets = record.kind === "discovered-project" ? record.sourceTargets : [];
+  const firstSeenAt =
+    record.kind === "discovered-project" ? record.firstSeenAt : record.registeredAt;
+  if (workspace === null) {
+    return {
+      schemaVersion: 1,
+      kind: "project-workspace",
+      workspaceKey: resolvePathProjectLogKey(homeDir, record.workspaceRoot),
+      projectKey: canonicalizeProjectKey(record.projectKey, aliases),
+      displayName: record.displayName,
+      workspaceRoot: record.workspaceRoot,
+      workspaceKind: record.workspaceKind,
+      gitCommonDir: null,
+      sourceTargets,
+      firstSeenAt,
+      lastSeenAt: record.lastSeenAt,
+      localOnly: true,
+      sourceContentStored: false,
+      available: false,
+    };
+  }
+  return {
+    schemaVersion: 1,
+    kind: "project-workspace",
+    workspaceKey: workspace.workspaceKey,
+    projectKey: workspace.projectKey,
+    displayName: basename(workspace.workspaceRoot) || parse(workspace.workspaceRoot).root,
+    workspaceRoot: workspace.workspaceRoot,
+    workspaceKind: workspace.workspaceKind,
+    gitCommonDir: workspace.gitCommonDir,
+    sourceTargets,
+    firstSeenAt,
+    lastSeenAt: record.lastSeenAt,
+    localOnly: true,
+    sourceContentStored: false,
+    available: true,
+  };
+}
+
+function mergeProjectWorkspaceSummary(
+  records: Map<string, ProjectWorkspaceSummary>,
+  next: ProjectWorkspaceSummary,
+): void {
+  const previous = records.get(next.workspaceKey);
+  if (previous === undefined) {
+    records.set(next.workspaceKey, next);
+    return;
+  }
+  const newer = next.lastSeenAt >= previous.lastSeenAt ? next : previous;
+  records.set(next.workspaceKey, {
+    ...newer,
+    projectKey: next.projectKey,
+    available: previous.available || next.available,
+    sourceTargets: mergeTargets(previous.sourceTargets, next.sourceTargets),
+    firstSeenAt: previous.firstSeenAt <= next.firstSeenAt ? previous.firstSeenAt : next.firstSeenAt,
+    lastSeenAt: previous.lastSeenAt >= next.lastSeenAt ? previous.lastSeenAt : next.lastSeenAt,
+  });
+}
+
+async function findNearestGitRoot(cwd: string): Promise<string | null> {
+  let current = cwd;
+  for (;;) {
+    try {
+      const marker = await lstat(join(current, ".git"));
+      if (marker.isDirectory() || marker.isFile()) return current;
+    } catch (error) {
+      if (!isNotFoundError(error)) throw error;
+    }
+    const parent = dirname(current);
+    if (parent === current) return null;
+    current = parent;
+  }
+}
+
+async function readDiscoveredProject(path: string): Promise<DiscoveredProjectRecordV1 | null> {
+  try {
+    return parseDiscoveredProject(JSON.parse(await readFile(path, "utf8")) as unknown);
+  } catch (error) {
+    if (isNotFoundError(error) || error instanceof ProjectRegistrationError) return null;
+    throw error;
+  }
+}
+
+async function readRegisteredProject(path: string): Promise<RegisteredProjectRecordV1 | null> {
+  try {
+    return parseRegisteredProject(JSON.parse(await readFile(path, "utf8")) as unknown);
+  } catch (error) {
+    if (isNotFoundError(error) || error instanceof ProjectRegistrationError) return null;
+    throw error;
+  }
+}
+
+async function readProjectWorkspace(path: string): Promise<ProjectWorkspaceRecordV1 | null> {
+  try {
+    return parseProjectWorkspace(JSON.parse(await readFile(path, "utf8")) as unknown);
+  } catch (error) {
+    if (isNotFoundError(error) || error instanceof ProjectRegistrationError) return null;
+    throw error;
+  }
+}
+
+async function readProjectAlias(path: string): Promise<ProjectAliasRecordV1 | null> {
+  try {
+    return parseProjectAlias(JSON.parse(await readFile(path, "utf8")) as unknown);
+  } catch (error) {
+    if (isNotFoundError(error) || error instanceof ProjectRegistrationError) return null;
+    throw error;
+  }
+}
+
+function parseDiscoveredProject(value: unknown): DiscoveredProjectRecordV1 {
+  const record = requireRecord(value);
+  if (
+    record.schemaVersion !== 1 ||
+    record.kind !== "discovered-project" ||
+    !isProjectKey(record.projectKey) ||
+    !isNonEmptyString(record.displayName) ||
+    !isAbsoluteString(record.workspaceRoot) ||
+    !isAbsoluteString(record.lastCwd) ||
+    !isWorkspaceKind(record.workspaceKind) ||
+    !isDiscoveryTargetArray(record.sourceTargets) ||
+    !(record.lastSessionKey === null || isNonEmptyString(record.lastSessionKey)) ||
+    !isNonEmptyString(record.firstSeenAt) ||
+    !isNonEmptyString(record.lastSeenAt) ||
+    record.localOnly !== true ||
+    record.sourceContentStored !== false
+  ) {
+    throw new ProjectRegistrationError("invalid", "Discovered project record is invalid.");
+  }
+  return record as unknown as DiscoveredProjectRecordV1;
+}
+
+function parseRegisteredProject(value: unknown): RegisteredProjectRecordV1 {
+  const record = requireRecord(value);
+  if (
+    record.schemaVersion !== 1 ||
+    record.kind !== "registered-project" ||
+    !isProjectKey(record.projectKey) ||
+    !isNonEmptyString(record.displayName) ||
+    !isAbsoluteString(record.workspaceRoot) ||
+    !isWorkspaceKind(record.workspaceKind) ||
+    !isNonEmptyString(record.registeredAt) ||
+    !isNonEmptyString(record.lastSeenAt) ||
+    record.localOnly !== true ||
+    record.sourceContentStored !== false
+  ) {
+    throw new ProjectRegistrationError("invalid", "Registered project record is invalid.");
+  }
+  return record as unknown as RegisteredProjectRecordV1;
+}
+
+function parseProjectWorkspace(value: unknown): ProjectWorkspaceRecordV1 {
+  const record = requireRecord(value);
+  if (
+    record.schemaVersion !== 1 ||
+    record.kind !== "project-workspace" ||
+    !isProjectKey(record.workspaceKey) ||
+    !isProjectKey(record.projectKey) ||
+    !isNonEmptyString(record.displayName) ||
+    !isAbsoluteString(record.workspaceRoot) ||
+    !isWorkspaceKind(record.workspaceKind) ||
+    !(record.gitCommonDir === null || isAbsoluteString(record.gitCommonDir)) ||
+    !isDiscoveryTargetArray(record.sourceTargets) ||
+    !isNonEmptyString(record.firstSeenAt) ||
+    !isNonEmptyString(record.lastSeenAt) ||
+    record.localOnly !== true ||
+    record.sourceContentStored !== false
+  ) {
+    throw new ProjectRegistrationError("invalid", "Project workspace record is invalid.");
+  }
+  return record as unknown as ProjectWorkspaceRecordV1;
+}
+
+function parseProjectAlias(value: unknown): ProjectAliasRecordV1 {
+  const record = requireRecord(value);
+  if (
+    record.schemaVersion !== 1 ||
+    record.kind !== "project-alias" ||
+    !isProjectKey(record.aliasProjectKey) ||
+    !isProjectKey(record.canonicalProjectKey) ||
+    record.aliasProjectKey === record.canonicalProjectKey ||
+    !isAbsoluteString(record.workspaceRoot) ||
+    !isNonEmptyString(record.createdAt) ||
+    !isNonEmptyString(record.updatedAt) ||
+    record.localOnly !== true ||
+    record.sourceContentStored !== false
+  ) {
+    throw new ProjectRegistrationError("invalid", "Project alias record is invalid.");
+  }
+  return record as unknown as ProjectAliasRecordV1;
+}
+
+function mergeDiscoveredRecord(
+  records: Map<string, DiscoveredProjectRecordV1>,
+  next: DiscoveredProjectRecordV1,
+): void {
+  const previous = records.get(next.projectKey);
+  if (previous === undefined) {
+    records.set(next.projectKey, next);
+    return;
+  }
+  const newer = next.lastSeenAt >= previous.lastSeenAt ? next : previous;
+  records.set(next.projectKey, {
+    ...newer,
+    sourceTargets: mergeTargets(previous.sourceTargets, next.sourceTargets),
+    firstSeenAt: previous.firstSeenAt <= next.firstSeenAt ? previous.firstSeenAt : next.firstSeenAt,
+    lastSeenAt: previous.lastSeenAt >= next.lastSeenAt ? previous.lastSeenAt : next.lastSeenAt,
+  });
+}
+
+function mergeRegisteredRecord(
+  records: Map<string, RegisteredProjectRecordV1>,
+  next: RegisteredProjectRecordV1,
+): void {
+  const previous = records.get(next.projectKey);
+  if (previous === undefined) {
+    records.set(next.projectKey, next);
+    return;
+  }
+  const newer = next.lastSeenAt >= previous.lastSeenAt ? next : previous;
+  records.set(next.projectKey, {
+    ...newer,
+    registeredAt:
+      previous.registeredAt <= next.registeredAt ? previous.registeredAt : next.registeredAt,
+    lastSeenAt: previous.lastSeenAt >= next.lastSeenAt ? previous.lastSeenAt : next.lastSeenAt,
+  });
+}
+
+function mergeTargets(
+  left: ProjectDiscoveryTarget[],
+  right: ProjectDiscoveryTarget[],
+): ProjectDiscoveryTarget[] {
+  return [...new Set([...left, ...right])].sort();
+}
+
+function normalizeSessionKey(value: string | null | undefined): string | null {
+  if (value === null || value === undefined) return null;
+  return /^session-[a-f0-9]{16}$/u.test(value) ? value : `session-${sha256Short(value)}`;
+}
+
+interface LegacyHookBinding {
+  target: ProjectDiscoveryTarget;
+  sessionKey: string;
+  cwd: string | null;
+  updatedAt: string;
+}
+
+async function listLegacyHookBindings(homeDir: string): Promise<LegacyHookBinding[]> {
+  const roots = [
+    join(homeDir, ".evodev", "state", "hooks", "sessions"),
+    join(homeDir, ".evodev", "STATE", "hooks", "sessions"),
+  ];
+  const bindings: LegacyHookBinding[] = [];
+  for (const root of roots) {
+    for (const sessionDir of await listDirectoryNames(root)) {
+      try {
+        const value = JSON.parse(
+          await readFile(join(root, sessionDir, "binding.json"), "utf8"),
+        ) as Record<string, unknown> | null;
+        if (
+          value === null ||
+          (value.target !== "claude" && value.target !== "codex") ||
+          !isNonEmptyString(value.sessionKey) ||
+          !(value.cwd === null || isAbsoluteString(value.cwd)) ||
+          !isNonEmptyString(value.updatedAt)
+        ) {
+          continue;
+        }
+        bindings.push({
+          target: value.target,
+          sessionKey: value.sessionKey,
+          cwd: value.cwd,
+          updatedAt: value.updatedAt,
+        });
+      } catch (error) {
+        if (!isNotFoundError(error) && !(error instanceof SyntaxError)) throw error;
+      }
+    }
+  }
+  return bindings;
+}
+
+async function listJsonFilePaths(path: string): Promise<string[]> {
+  try {
+    return (await readdir(path, { withFileTypes: true }))
+      .filter((entry) => entry.isFile() && entry.name.endsWith(".json"))
+      .map((entry) => join(path, entry.name))
+      .sort();
+  } catch (error) {
+    if (isNotFoundError(error)) return [];
+    throw error;
+  }
+}
+
+async function listDirectoryNames(path: string): Promise<string[]> {
+  try {
+    return (await readdir(path, { withFileTypes: true }))
+      .filter((entry) => entry.isDirectory())
+      .map((entry) => entry.name)
+      .sort();
+  } catch (error) {
+    if (isNotFoundError(error)) return [];
+    throw error;
+  }
+}
+
+function assertProjectKey(value: string): void {
+  if (!isProjectKey(value)) {
+    throw new ProjectRegistrationError("invalid", "projectKey is invalid.");
+  }
+}
+
+function isProjectKey(value: unknown): value is string {
+  return (
+    typeof value === "string" &&
+    value !== "." &&
+    value !== ".." &&
+    /^[A-Za-z0-9._-]{1,120}$/.test(value)
+  );
+}
+
+function isNonEmptyString(value: unknown): value is string {
+  return typeof value === "string" && value.trim() !== "";
+}
+
+function isAbsoluteString(value: unknown): value is string {
+  return isNonEmptyString(value) && isAbsolute(value);
+}
+
+function isWorkspaceKind(value: unknown): value is ProjectWorkspaceKind {
+  return value === "git" || value === "directory";
+}
+
+function isDiscoveryTargetArray(value: unknown): value is ProjectDiscoveryTarget[] {
+  return (
+    Array.isArray(value) &&
+    value.length > 0 &&
+    value.every((item) => item === "claude" || item === "codex")
+  );
+}
+
+function requireRecord(value: unknown): Record<string, unknown> {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    throw new ProjectRegistrationError("invalid", "Project record must be an object.");
+  }
+  return value as Record<string, unknown>;
+}