Merge pull request #986 from web3dev1337/fix/smart-projects-root-detection

fix: smart legacy ~/GitHub detection based on worktree layout

Author: web3dev1337

ai-memory/fix-smart-projects-root-detection-92cc2e6/init.md

@@ -0,0 +1 @@
+Don't grandfather ~/GitHub as projects root when repos are flat clones (no worktree layout).

ai-memory/fix-smart-projects-root-detection-92cc2e6/progress.md

@@ -0,0 +1,5 @@
+- [x] Add hasWorktreeLayout() and countWorktreeLayoutRepos() helpers
+- [x] Fix bootstrapProjectsRoot() to check worktree layout before grandfathering
+- [x] Add skip logging in server/index.js
+- [x] Add tests (hasWorktreeLayout, countWorktreeLayoutRepos, flat clone skip, worktree grandfather)
+- [x] All 550 tests pass

server/index.js

@@ -79,8 +79,16 @@ if (legacyCompatibilityState.shouldUseLegacyDir) {
   });
 }
 if (projectsRootBootstrap.usingLegacyProjectsRoot) {
-  logger.info('Using legacy ~/GitHub as the projects root until ~/.agent-workspace/projects is populated', {
-    projectsDir: projectsRootBootstrap.projectsDir
+  logger.info('Using legacy ~/GitHub as the projects root (worktree layout detected)', {
+    projectsDir: projectsRootBootstrap.projectsDir,
+    total: projectsRootBootstrap.total,
+    worktree: projectsRootBootstrap.worktree
+  });
+} else if (projectsRootBootstrap.legacySkipReason) {
+  logger.info('Skipping legacy ~/GitHub — repos do not use worktree layout', {
+    reason: projectsRootBootstrap.legacySkipReason,
+    total: projectsRootBootstrap.total,
+    worktree: projectsRootBootstrap.worktree
   });
 }
 

server/utils/pathUtils.js

@@ -325,8 +325,90 @@ function hasVisibleEntries(dirPath) {
 }
 
 /**
- * Preserve existing ~/GitHub installs unless the new projects root is already populated
- * or the user explicitly chose AGENT_WORKSPACE_PROJECTS_DIR.
+ * Check whether a directory looks like a repo using the worktree layout
+ * (has a master/ or main/ subdirectory containing a .git file or folder).
+ */
+function hasWorktreeLayout(dirPath) {
+  const fs = require('fs');
+  for (const name of ['master', 'main']) {
+    const candidate = path.join(dirPath, name);
+    try {
+      const stat = fs.statSync(candidate);
+      if (!stat.isDirectory()) continue;
+      const gitPath = path.join(candidate, '.git');
+      fs.statSync(gitPath);
+      return true;
+    } catch {
+      // not found, try next
+    }
+  }
+  return false;
+}
+
+function isGitRepo(dirPath) {
+  const fs = require('fs');
+  try {
+    fs.statSync(path.join(dirPath, '.git'));
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+const MAX_SCAN_DEPTH = 8;
+
+/**
+ * Recursively scan a directory tree to count repos and how many use
+ * worktree layout. Stops recursing into directories that are repos
+ * (so it never crawls node_modules, .git internals, etc.).
+ * Depth-limited to MAX_SCAN_DEPTH as a safety net.
+ * Returns { total, worktree } counts.
+ */
+function countWorktreeLayoutRepos(dirPath) {
+  const fs = require('fs');
+  let total = 0;
+  let worktree = 0;
+
+  function scan(dir, depth) {
+    if (depth > MAX_SCAN_DEPTH) return;
+
+    let entries;
+    try {
+      entries = fs.readdirSync(dir).filter((e) => !String(e || '').startsWith('.'));
+    } catch {
+      return;
+    }
+
+    for (const entry of entries) {
+      const entryPath = path.join(dir, entry);
+      try {
+        if (!fs.statSync(entryPath).isDirectory()) continue;
+      } catch {
+        continue;
+      }
+
+      if (hasWorktreeLayout(entryPath)) {
+        total++;
+        worktree++;
+      } else if (isGitRepo(entryPath)) {
+        total++;
+      } else {
+        scan(entryPath, depth + 1);
+      }
+    }
+  }
+
+  scan(dirPath, 0);
+  return { total, worktree };
+}
+
+/**
+ * Preserve existing ~/GitHub installs only when a meaningful portion of its
+ * repos use the worktree layout (master/ or main/ subdirectory with .git).
+ * If the legacy dir is mostly flat clones, skip grandfathering so new repos
+ * get created under ~/.agent-workspace/projects/ with proper layout.
+ *
+ * Configurable via AGENT_WORKSPACE_PROJECTS_DIR env var (explicit override).
  */
 function bootstrapProjectsRoot() {
   const fs = require('fs');
@@ -346,11 +428,24 @@ function bootstrapProjectsRoot() {
     return { usingLegacyProjectsRoot: false, projectsDir };
   }
 
+  // Check if the legacy dir actually uses worktree layout
+  const { total, worktree } = countWorktreeLayoutRepos(legacyDir);
+  if (total > 0 && worktree === 0) {
+    // All flat clones, no worktree layout at all — don't grandfather
+    return { usingLegacyProjectsRoot: false, projectsDir, legacySkipReason: 'no-worktree-layout', total, worktree };
+  }
+  if (total >= 4 && worktree / total < 0.25) {
+    // Very few repos use worktree layout — don't grandfather
+    return { usingLegacyProjectsRoot: false, projectsDir, legacySkipReason: 'insufficient-worktree-layout', total, worktree };
+  }
+
   process.env.AGENT_WORKSPACE_PROJECTS_DIR = legacyDir;
   return {
     usingLegacyProjectsRoot: true,
     projectsDir: legacyDir,
-    legacyDir
+    legacyDir,
+    total,
+    worktree
   };
 }
 
@@ -403,6 +498,8 @@ module.exports = {
   getLegacyProjectsRoot,
   migrateFromOrchestratorDir,
   bootstrapProjectsRoot,
+  hasWorktreeLayout,
+  countWorktreeLayoutRepos,
   resolveRepoConfigPath,
   REPO_CONFIG_NAME,
   LEGACY_REPO_CONFIG_NAME

tests/unit/pathUtils.test.js

@@ -45,9 +45,11 @@ describe('pathUtils', () => {
     expect(getTrailingPathLabel('/tmp/repo/work2', 1)).toBe('work2');
   });
 
-  test('bootstrapProjectsRoot falls back to legacy GitHub when the new projects root is empty', () => {
+  test('bootstrapProjectsRoot falls back to legacy GitHub when repos use worktree layout', () => {
     const tmpHome = fs.mkdtempSync(path.join(os.tmpdir(), 'path-utils-home-'));
-    fs.mkdirSync(path.join(tmpHome, 'GitHub', 'games'), { recursive: true });
+    // Create repos with worktree layout (master/ with .git)
+    fs.mkdirSync(path.join(tmpHome, 'GitHub', 'repo-a', 'master', '.git'), { recursive: true });
+    fs.mkdirSync(path.join(tmpHome, 'GitHub', 'repo-b', 'master', '.git'), { recursive: true });
 
     const {
       bootstrapProjectsRoot,
@@ -63,6 +65,26 @@ describe('pathUtils', () => {
     expect(process.env.AGENT_WORKSPACE_PROJECTS_DIR).toBe(getLegacyProjectsRoot());
   });
 
+  test('bootstrapProjectsRoot skips legacy GitHub when repos are all flat clones', () => {
+    const tmpHome = fs.mkdtempSync(path.join(os.tmpdir(), 'path-utils-home-'));
+    // Flat clones — no master/ subdirectory, just .git at root
+    fs.mkdirSync(path.join(tmpHome, 'GitHub', 'repo-a', '.git'), { recursive: true });
+    fs.mkdirSync(path.join(tmpHome, 'GitHub', 'repo-b', '.git'), { recursive: true });
+    fs.mkdirSync(path.join(tmpHome, 'GitHub', 'repo-c', '.git'), { recursive: true });
+
+    const {
+      bootstrapProjectsRoot,
+      getProjectsRoot,
+      getLegacyProjectsRoot
+    } = loadPathUtils(tmpHome);
+
+    const result = bootstrapProjectsRoot();
+
+    expect(result.usingLegacyProjectsRoot).toBe(false);
+    expect(result.legacySkipReason).toBe('no-worktree-layout');
+    expect(getProjectsRoot()).not.toBe(getLegacyProjectsRoot());
+  });
+
   test('bootstrapProjectsRoot keeps the new projects root when it is already populated', () => {
     const tmpHome = fs.mkdtempSync(path.join(os.tmpdir(), 'path-utils-home-'));
     fs.mkdirSync(path.join(tmpHome, 'GitHub', 'games'), { recursive: true });
@@ -82,6 +104,48 @@ describe('pathUtils', () => {
     expect(process.env.AGENT_WORKSPACE_PROJECTS_DIR).toBeUndefined();
   });
 
+  test('hasWorktreeLayout detects master/ with .git', () => {
+    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'wt-layout-'));
+    fs.mkdirSync(path.join(tmpDir, 'master', '.git'), { recursive: true });
+
+    const { hasWorktreeLayout } = loadPathUtils();
+    expect(hasWorktreeLayout(tmpDir)).toBe(true);
+  });
+
+  test('hasWorktreeLayout detects main/ with .git', () => {
+    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'wt-layout-'));
+    fs.mkdirSync(path.join(tmpDir, 'main', '.git'), { recursive: true });
+
+    const { hasWorktreeLayout } = loadPathUtils();
+    expect(hasWorktreeLayout(tmpDir)).toBe(true);
+  });
+
+  test('hasWorktreeLayout returns false for flat clones', () => {
+    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'wt-layout-'));
+    fs.mkdirSync(path.join(tmpDir, '.git'), { recursive: true });
+    fs.mkdirSync(path.join(tmpDir, 'src'), { recursive: true });
+
+    const { hasWorktreeLayout } = loadPathUtils();
+    expect(hasWorktreeLayout(tmpDir)).toBe(false);
+  });
+
+  test('countWorktreeLayoutRepos counts repos at multiple nesting depths', () => {
+    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'wt-count-'));
+    // Depth 1: worktree layout
+    fs.mkdirSync(path.join(tmpDir, 'repo-a', 'master', '.git'), { recursive: true });
+    // Depth 2 (nested category): worktree layout
+    fs.mkdirSync(path.join(tmpDir, 'games', 'zoo-game', 'master', '.git'), { recursive: true });
+    // Depth 2: flat clone
+    fs.mkdirSync(path.join(tmpDir, 'games', 'flat-game', '.git'), { recursive: true });
+    // Depth 4 (deep nesting): worktree layout
+    fs.mkdirSync(path.join(tmpDir, 'games', 'hytopia', 'games', 'hyfire', 'master', '.git'), { recursive: true });
+
+    const { countWorktreeLayoutRepos } = loadPathUtils();
+    const result = countWorktreeLayoutRepos(tmpDir);
+    expect(result.total).toBe(4);
+    expect(result.worktree).toBe(3);
+  });
+
   test('getAgentWorkspaceDir falls back to legacy data when legacy has more workspaces', () => {
     const tmpHome = fs.mkdtempSync(path.join(os.tmpdir(), 'path-utils-home-'));
     fs.mkdirSync(path.join(tmpHome, '.agent-workspace', 'workspaces'), { recursive: true });