feat: add project scanner with full-drive mode

package.json

@@ -9,7 +9,7 @@
     "start": "next start",
     "lint": "next lint",
     "typecheck": "tsc --noEmit",
-    "test": "node --test tests/bootstrap.test.mjs && node --import tsx --test tests/lib/parser.test.ts && node --import tsx --test tests/lib/pathing.test.ts && node --import tsx --test tests/lib/kanban.test.ts && node --import tsx --test tests/lib/read-issues.test.ts && node --import tsx --test tests/lib/bd-path.test.ts && node --import tsx --test tests/lib/bridge.test.ts && node --import tsx --test tests/lib/mutations.test.ts && node --import tsx --test tests/lib/writeback.test.ts && node --import tsx --test tests/lib/registry.test.ts && node --import tsx --test tests/api/projects-route.test.ts && node --import tsx --test tests/api/mutations-routes.test.ts && node --test tests/guards/no-direct-jsonl-write.test.mjs && node --test tests/guards/no-inline-style-in-kanban.test.mjs && node --test tests/guards/kanban-responsive-contract.test.mjs"
+    "test": "node --test tests/bootstrap.test.mjs && node --import tsx --test tests/lib/parser.test.ts && node --import tsx --test tests/lib/pathing.test.ts && node --import tsx --test tests/lib/kanban.test.ts && node --import tsx --test tests/lib/read-issues.test.ts && node --import tsx --test tests/lib/bd-path.test.ts && node --import tsx --test tests/lib/bridge.test.ts && node --import tsx --test tests/lib/mutations.test.ts && node --import tsx --test tests/lib/writeback.test.ts && node --import tsx --test tests/lib/registry.test.ts && node --import tsx --test tests/lib/scanner.test.ts && node --import tsx --test tests/api/projects-route.test.ts && node --import tsx --test tests/api/mutations-routes.test.ts && node --test tests/guards/no-direct-jsonl-write.test.mjs && node --test tests/guards/no-inline-style-in-kanban.test.mjs && node --test tests/guards/kanban-responsive-contract.test.mjs"
   },
   "dependencies": {
     "framer-motion": "^11.18.2",

src/app/api/scan/route.ts

@@ -0,0 +1,44 @@
+import { NextResponse } from 'next/server';
+
+import { scanForProjects } from '../../../lib/scanner';
+import type { ScanMode } from '../../../lib/scanner';
+
+export const runtime = 'nodejs';
+
+function parseMode(value: string | null): ScanMode {
+  if (!value || value === 'default') {
+    return 'default';
+  }
+
+  if (value === 'full-drive') {
+    return 'full-drive';
+  }
+
+  throw new Error('Invalid scan mode. Use mode=default or mode=full-drive.');
+}
+
+function parseDepth(value: string | null): number | undefined {
+  if (!value) {
+    return undefined;
+  }
+
+  const parsed = Number.parseInt(value, 10);
+  if (!Number.isFinite(parsed) || parsed < 0) {
+    throw new Error('Depth must be a non-negative integer.');
+  }
+
+  return parsed;
+}
+
+export async function GET(request: Request): Promise<Response> {
+  try {
+    const url = new URL(request.url);
+    const mode = parseMode(url.searchParams.get('mode'));
+    const maxDepth = parseDepth(url.searchParams.get('depth'));
+    const result = await scanForProjects({ mode, maxDepth });
+    return NextResponse.json(result, { status: 200 });
+  } catch (error) {
+    const message = error instanceof Error ? error.message : 'Failed to scan projects.';
+    return NextResponse.json({ error: message }, { status: 400 });
+  }
+}

src/lib/scanner.ts

@@ -0,0 +1,223 @@
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+
+import { canonicalizeWindowsPath, toDisplayPath, windowsPathKey } from './pathing';
+import { listProjects } from './registry';
+
+export type ScanMode = 'default' | 'full-drive';
+
+export interface ScannerProject {
+  root: string;
+  key: string;
+  displayPath: string;
+}
+
+export interface ScanStats {
+  scannedDirectories: number;
+  ignoredDirectories: number;
+  skippedDirectories: number;
+  elapsedMs: number;
+}
+
+export interface ScanOptions {
+  mode?: ScanMode;
+  maxDepth?: number;
+  roots?: string[];
+  ignoreDirectories?: string[];
+}
+
+export interface ScanResult {
+  mode: ScanMode;
+  roots: string[];
+  projects: ScannerProject[];
+  stats: ScanStats;
+}
+
+const DEFAULT_MAX_DEPTH = 6;
+const DEFAULT_IGNORE_DIRECTORIES = [
+  'node_modules',
+  '.git',
+  '.next',
+  'dist',
+  'build',
+  'out',
+  'coverage',
+  'artifacts',
+  'logs',
+  '.worktrees', // TODO: confirm whether worktrees should be scan targets.
+];
+
+function userProfileRoot(): string {
+  return process.env.USERPROFILE?.trim() || os.homedir();
+}
+
+function toCanonicalRoot(input: string): string {
+  return canonicalizeWindowsPath(input);
+}
+
+function shouldSkipFsError(error: NodeJS.ErrnoException): boolean {
+  return error.code === 'ENOENT' || error.code === 'ENOTDIR' || error.code === 'EACCES' || error.code === 'EPERM';
+}
+
+async function ensureDirectoryExists(input: string): Promise<string | null> {
+  try {
+    const stat = await fs.stat(input);
+    return stat.isDirectory() ? input : null;
+  } catch (error) {
+    if (shouldSkipFsError(error as NodeJS.ErrnoException)) {
+      return null;
+    }
+    throw error;
+  }
+}
+
+async function resolveFullDriveRoots(): Promise<string[]> {
+  const candidates = ['C:\\', 'D:\\'];
+  const roots: string[] = [];
+
+  for (const candidate of candidates) {
+    const existing = await ensureDirectoryExists(candidate);
+    if (existing) {
+      roots.push(existing);
+    }
+  }
+
+  return roots;
+}
+
+export async function resolveScanRoots(options: ScanOptions = {}): Promise<string[]> {
+  const mode: ScanMode = options.mode ?? 'default';
+  const registryProjects = await listProjects();
+  const roots = [
+    userProfileRoot(),
+    ...registryProjects.map((project) => project.path),
+    ...(options.roots ?? []),
+  ];
+
+  if (mode === 'full-drive') {
+    roots.push(...(await resolveFullDriveRoots()));
+  }
+
+  const seen = new Set<string>();
+  const normalizedRoots: string[] = [];
+
+  for (const root of roots) {
+    const normalized = toCanonicalRoot(root);
+    const key = windowsPathKey(normalized);
+    if (seen.has(key)) {
+      continue;
+    }
+
+    const existing = await ensureDirectoryExists(normalized);
+    if (!existing) {
+      continue;
+    }
+
+    seen.add(key);
+    normalizedRoots.push(existing);
+  }
+
+  return normalizedRoots;
+}
+
+function buildIgnoreSet(additional: string[] = []): Set<string> {
+  return new Set(
+    [...DEFAULT_IGNORE_DIRECTORIES, ...additional].map((entry) => entry.trim().toLowerCase()).filter(Boolean),
+  );
+}
+
+function recordProject(projects: Map<string, ScannerProject>, root: string): void {
+  const normalized = toCanonicalRoot(root);
+  const key = windowsPathKey(normalized);
+  if (!projects.has(key)) {
+    projects.set(key, {
+      root: normalized,
+      key,
+      displayPath: toDisplayPath(normalized),
+    });
+  }
+}
+
+async function scanRoot(
+  root: string,
+  maxDepth: number,
+  ignoreSet: Set<string>,
+  projects: Map<string, ScannerProject>,
+  stats: ScanStats,
+): Promise<void> {
+  const queue: Array<{ dir: string; depth: number }> = [{ dir: root, depth: 0 }];
+
+  while (queue.length > 0) {
+    const current = queue.shift();
+    if (!current) {
+      continue;
+    }
+
+    stats.scannedDirectories += 1;
+    let entries: fs.Dirent[];
+    try {
+      entries = await fs.readdir(current.dir, { withFileTypes: true });
+    } catch (error) {
+      if (shouldSkipFsError(error as NodeJS.ErrnoException)) {
+        stats.skippedDirectories += 1;
+        continue;
+      }
+      throw error;
+    }
+
+    let hasBeads = false;
+    for (const entry of entries) {
+      if (!entry.isDirectory()) {
+        continue;
+      }
+
+      if (entry.name === '.beads') {
+        hasBeads = true;
+        continue;
+      }
+
+      const entryName = entry.name.toLowerCase();
+      if (ignoreSet.has(entryName)) {
+        stats.ignoredDirectories += 1;
+        continue;
+      }
+
+      if (current.depth < maxDepth) {
+        queue.push({ dir: path.join(current.dir, entry.name), depth: current.depth + 1 });
+      }
+    }
+
+    if (hasBeads) {
+      recordProject(projects, current.dir);
+    }
+  }
+}
+
+export async function scanForProjects(options: ScanOptions = {}): Promise<ScanResult> {
+  const mode: ScanMode = options.mode ?? 'default';
+  const maxDepth = options.maxDepth ?? DEFAULT_MAX_DEPTH;
+  const ignoreSet = buildIgnoreSet(options.ignoreDirectories);
+  const roots = await resolveScanRoots(options);
+  const projects = new Map<string, ScannerProject>();
+  const stats: ScanStats = {
+    scannedDirectories: 0,
+    ignoredDirectories: 0,
+    skippedDirectories: 0,
+    elapsedMs: 0,
+  };
+  const start = Date.now();
+
+  for (const root of roots) {
+    await scanRoot(root, maxDepth, ignoreSet, projects, stats);
+  }
+
+  stats.elapsedMs = Date.now() - start;
+
+  return {
+    mode,
+    roots,
+    projects: Array.from(projects.values()),
+    stats,
+  };
+}

tests/lib/scanner.test.ts

@@ -0,0 +1,68 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+
+import { addProject } from '../../src/lib/registry';
+import { scanForProjects, resolveScanRoots } from '../../src/lib/scanner';
+import { canonicalizeWindowsPath, sameWindowsPath, windowsPathKey } from '../../src/lib/pathing';
+
+async function withTempUserProfile(run: (userProfile: string) => Promise<void>): Promise<void> {
+  const previous = process.env.USERPROFILE;
+  const tempDir = await fs.mkdtemp(path.join(os.tmpdir(), 'beadboard-scan-'));
+  process.env.USERPROFILE = tempDir;
+
+  try {
+    await run(tempDir);
+  } finally {
+    if (previous === undefined) {
+      delete process.env.USERPROFILE;
+    } else {
+      process.env.USERPROFILE = previous;
+    }
+
+    await fs.rm(tempDir, { recursive: true, force: true });
+  }
+}
+
+test('resolveScanRoots includes profile and registry roots by default', async () => {
+  await withTempUserProfile(async (userProfile) => {
+    const registryRoot = path.join(userProfile, 'Registered');
+    await fs.mkdir(registryRoot, { recursive: true });
+    await addProject(registryRoot);
+
+    const roots = await resolveScanRoots();
+
+    assert.equal(roots.some((root) => sameWindowsPath(root, userProfile)), true);
+    assert.equal(roots.some((root) => sameWindowsPath(root, registryRoot)), true);
+    assert.equal(roots.some((root) => windowsPathKey(root) === windowsPathKey('C:\\')), false);
+  });
+});
+
+test('resolveScanRoots includes full-drive roots only when requested', async () => {
+  await withTempUserProfile(async () => {
+    const roots = await resolveScanRoots({ mode: 'full-drive' });
+    assert.equal(roots.some((root) => windowsPathKey(root) === windowsPathKey('C:\\')), true);
+  });
+});
+
+test('scanForProjects respects depth limits and ignore list', async () => {
+  await withTempUserProfile(async (userProfile) => {
+    const projectRoot = path.join(userProfile, 'ProjectA');
+    await fs.mkdir(path.join(projectRoot, '.beads'), { recursive: true });
+
+    const ignoredRoot = path.join(userProfile, 'node_modules', 'Ignored');
+    await fs.mkdir(path.join(ignoredRoot, '.beads'), { recursive: true });
+
+    const deepRoot = path.join(userProfile, 'Deep', 'Level1', 'Level2', 'ProjectDeep');
+    await fs.mkdir(path.join(deepRoot, '.beads'), { recursive: true });
+
+    const result = await scanForProjects({ maxDepth: 1 });
+    const keys = result.projects.map((project) => project.key);
+
+    assert.equal(keys.includes(windowsPathKey(canonicalizeWindowsPath(projectRoot))), true);
+    assert.equal(keys.includes(windowsPathKey(canonicalizeWindowsPath(ignoredRoot))), false);
+    assert.equal(keys.includes(windowsPathKey(canonicalizeWindowsPath(deepRoot))), false);
+  });
+});