Node.js 20.12.2 compatibility: `fs.promises.readdir()` with `recursive: true` not implemented in test environment

[KlementMultiverse]

Problem

Issue #27 reports that ai-devkit fails on Node.js 20.12.2. The root cause is likely in how the toolkit discovers and initializes .ai-devkit.json files during setup or project scanning.

Node.js 20.12.2 shipped with fs.promises.readdir() but the recursive: true option (added in Node 18.17.0) may not be fully implemented or has edge cases in that specific patch version. When ai-devkit init or the agent list command recursively scans directories, it either:

1. Throws an error because recursive: true is unsupported
2. Returns incomplete results, missing config files
3. Hangs on certain directory structures (symlinks, node_modules)

Why this matters

Developers on Node 20.12.2 cannot use ai-devkit init at all, blocking onboarding. Even if they downgrade Node, they hit silent failures where the toolkit doesn't find their config files, making agent status detection fail (related to #34).

What we need to fix

Find all calls to fs.promises.readdir() with recursive: true in the codebase (likely in the config loader or project scanner). Replace the recursive option with a manual recursive walk that:

• Uses fs.promises.readdir() without recursive: true
• Implements depth-first traversal explicitly
• Skips node_modules, .git, and other common ignore patterns
• Works consistently on Node 18.x, 20.x, and 22.x

Example fallback pattern:

async function walkDir(dir: string, depth = 0): Promise<string[]> {
  const entries = await fs.promises.readdir(dir);
  const results: string[] = [];
  for (const entry of entries) {
    if (['node_modules', '.git', '.next'].includes(entry)) continue;
    const full = path.join(dir, entry);
    results.push(full);
    const stat = await fs.promises.stat(full);
    if (stat.isDirectory()) results.push(...await walkDir(full, depth + 1));
  }
  return results;
}

Test case

node -v  # v20.12.2
npm install ai-devkit
npx ai-devkit init
# Should complete successfully without "recursive is not supported" or hanging

Related

This indirectly affects #34 (agent list showing wrong status) because if config discovery fails silently, the agent registry can't load properly.

---

Contributed by Klement Gunndu

[KlementMultiverse]

Withdrawing this issue. Apologies for any inconvenience.