perf(init): tighten list-dir hot loop + emit POSIX paths (#815)

## Summary

Focused code-audit cleanup of `src/lib/init/tools/list-dir.ts`.
No behavior changes on POSIX hosts; Windows hosts now get a
consistent wire contract.

## What changed

### Correctness: emit POSIX-separator paths

`path.relative(cwd, ...)` returns native separators, so Windows
hosts were sending paths like \`src\\app.ts\` on the Mastra wire.
Two downstream callers had \`replaceAll(\"\\\\\", \"/\")\` patches
to cope — one (\`workflow-inputs.ts::preReadCommonFiles\`, the
direct list-dir consumer) is cleaned up here; the other
(\`formatters.ts\`, normalizing data from a different source) stays
as-is.

The existing \`filesystem-tools.test.ts\` already asserted
\`src/app.ts\` (POSIX) and would have failed on Windows pre-fix.

### Perf: prune the hot loop

Per-entry changes in \`walkDirectory\`:

1. \`dir + NATIVE_SEP + entry.name\` instead of \`path.join(...)\` —
manual concat is ~10× faster in V8 since inputs are already clean.
2. \`abs.slice(state.cwdPrefixLen)\` instead of \`path.relative(...)\` —
O(1) slice instead of a parse-and-allocate call, since \`dir\` always
starts with \`cwd + sep\`.
3. \`cwdPrefixLen\` cached once at walk entry rather than recomputed per
dirent.
4. Dropped the redundant mid-loop \`reachedWalkLimit\` call (the
function-entry guard handles \`depth\`; an inline \`state.entries.length
>= state.maxEntries\` check handles the cap).
5. Same manual-concat fix applied to the recursion call site.

Microbench on a 500-entry recursive listing (30 runs, 3 warmup):

| Version | p50 |
|---|---:|
| Before | 1.705 ms |
| After | **1.130 ms** |

−34% at p50. Absolute numbers are small in both cases because
list-dir isn't on a hot path (called once per wizard step), but
cleanup stacked on top of the correctness fix.

## New test coverage

Added \`test/lib/init/tools/list-dir.test.ts\` with 11 dedicated tests.
Pre-PR, list-dir was covered by a single smoke test in
\`filesystem-tools.test.ts\`.

## Test plan

- [x] \`bunx tsc --noEmit\` — clean
- [x] \`bun run lint\` — clean (1 pre-existing markdown.ts warning,
unrelated)
- [x] \`bun test test/lib/init/\` — **135 pass, 0 fail** (+11 new)
- [x] \`bun test --timeout 15000 test/lib test/commands test/types\` —
**5664 pass, 0 fail**
- [x] \`bun test test/isolated\` — 138 pass
- [x] Microbench before/after — −34% p50 on 500-entry fixture

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: BYK

AGENTS.md

@@ -1035,7 +1035,7 @@ mock.module("./some-module", () => ({
 * **AuthError constructor takes reason first, message second**: \`AuthError(reason: AuthErrorReason, message?: string)\` where \`AuthErrorReason\` is \`"not\_authenticated" | "expired" | "invalid"\`. Easy to accidentally swap args as \`new AuthError("Token expired", "expired")\` — the string \`"Token expired"\` gets assigned as \`reason\` (invalid enum value). Tests aren't type-checked (tsconfig excludes them), so TypeScript won't catch this. Correct: \`new AuthError("expired", "Token expired")\`. Default messages exist for each reason, so the second arg is often unnecessary.
 
 <!-- lore:019db4d8-2b12-7621-a157-12d34789fa43 -->
-* **DEFAULT\_SKIP\_DIRS prunes dist/build/.next — narrow for build-output scans**: \*\*scan module walker gotchas\*\*: (1) \`DEFAULT\_SKIP\_DIRS\` in \`src/lib/scan/ignore.ts\` prunes broadly: \`node\_modules\`, VCS, plus \`dist\`, \`build\`, \`target\`, \`.next\`, \`.nuxt\`, \`.output\`, \`vendor\`, \`.gradle\`, \`.bundle\`, \`coverage\`, \`.cache\`, \`.turbo\`. When walker starts AT \`dist/\`, skip list doesn't apply to cwd itself; recursing from parent prunes. For \`sourcemap/inject.ts\`, pass narrowed \`alwaysSkipDirs: \["node\_modules"]\` + \`respectGitignore: false\` to scan build outputs. (2) When \`extensions\` is set, walker skips binary NUL-sniff entirely. (3) walkFiles migration checklist — verify 5 knobs: \`respectGitignore\` (default true), \`hidden\` (default true, include), \`alwaysSkipDirs\` (default broad), \`extensions\` (skips NUL-sniff), \`followSymlinks\` (default false). DFS order differs from files-first-then-dirs — verify no ordering contract at call sites.
+* **DEFAULT\_SKIP\_DIRS prunes dist/build/.next — narrow for build-output scans**: \*\*scan module walkFiles migration gotchas\*\*: (1) \`DEFAULT\_SKIP\_DIRS\` in \`src/lib/scan/ignore.ts\` prunes broadly: \`node\_modules\`, VCS, \`dist\`, \`build\`, \`target\`, \`.next\`, \`.nuxt\`, \`.output\`, \`vendor\`, \`.gradle\`, \`.bundle\`, \`coverage\`, \`.cache\`, \`.turbo\`. Walker starting AT \`dist/\` doesn't prune cwd itself. For \`sourcemap/inject.ts\`, pass narrowed \`alwaysSkipDirs: \["node\_modules"]\` + \`respectGitignore: false\`. (2) \`walkFiles\` defaults \`maxFileSize: 256KB\` — silently skips large JS bundles (webpack/rollup/Next.js chunks routinely exceed this). Pass \`maxFileSize: Number.POSITIVE\_INFINITY\` when replacing unlimited \`readdir\` loops. (3) \`walkFiles\` enforces \`path.isAbsolute(opts.cwd)\` and throws on relative paths. CLI users pass \`./dist\`; callers must \`resolvePath(dir)\` before handing to walker. (4) When \`extensions\` is set, walker skips binary NUL-sniff. (5) Migration checklist: verify \`respectGitignore\`, \`hidden\`, \`alwaysSkipDirs\`, \`extensions\`, \`followSymlinks\`, \`maxFileSize\`, absolute-cwd. DFS order differs from files-first-then-dirs.
 
 <!-- lore:019dafc7-8ee7-7249-9505-5b32e66fb03c -->
 * **mapFilesConcurrent skips null but not empty arrays — callers must return null for no-op**: Scan/formatter off-by-ones: (1) \`mapFilesConcurrent\` in \`src/lib/scan/concurrent.ts\` filters \`null\` but NOT empty arrays — fires \`onResult\` per empty result. Callers (e.g. \`processEntry\` in \`dsn/code-scanner.ts\`) must return \`null\` (not \`\[]\`) for no-op files (~99% of 10k-file walks). Stream variant filters both. (2) \`collectGlob\`/\`collectGrep\` must NOT forward \`maxResults\` to underlying iterator — collector drains uncapped, sets \`truncated=true\` on overshoot; forwarding stops iterator at exactly N without \`truncated\`. (3) \`filterFields\` in \`formatters/json.ts\` uses dot-notation — property tests must use \`\[a-zA-Z0-9\_]\` charset to avoid ambiguous keys with dots.

src/lib/constants.ts

@@ -24,6 +24,14 @@ export const DEFAULT_SENTRY_HOST = "sentry.io";
 /** Default Sentry SaaS URL (control silo for OAuth and region discovery) */
 export const DEFAULT_SENTRY_URL = `https://${DEFAULT_SENTRY_HOST}`;
 
+/**
+ * Name of the JavaScript package directory — used as both a skip target
+ * when walking project trees (DSN scanner, sourcemap discovery, init
+ * wizard) and as a path segment when detecting how the CLI itself was
+ * installed (upgrade detection).
+ */
+export const NODE_MODULES_DIRNAME = "node_modules";
+
 /** Matches strings that already start with http:// or https:// */
 const HAS_PROTOCOL_RE = /^https?:\/\//i;
 

src/lib/init/tools/list-dir.ts

@@ -1,43 +1,50 @@
 import fs from "node:fs";
 import path from "node:path";
+import { NODE_MODULES_DIRNAME } from "../../constants.js";
+import { normalizePath } from "../../scan/index.js";
 import type { DirEntry, ListDirPayload, ToolResult } from "../types.js";
 import { safePath } from "./shared.js";
 import type { InitToolDefinition } from "./types.js";
 
+const NATIVE_SEP = path.sep;
+
 /**
  * List files and directories within the workflow sandbox.
+ *
+ * Paths in the result are POSIX-normalized (`/`-separated) regardless
+ * of host OS, so the Mastra agent sees a consistent wire shape.
  */
 export async function listDir(payload: ListDirPayload): Promise<ToolResult> {
   const { cwd, params } = payload;
   const targetPath = safePath(cwd, params.path);
   const maxDepth = params.maxDepth ?? 3;
   const maxEntries = params.maxEntries ?? 500;
   const recursive = params.recursive ?? false;
-  const walkState = {
+  const state: WalkState = {
     cwd,
-    entries: [] as DirEntry[],
+    // Cached prefix length used to turn an absolute native path into a
+    // cwd-relative POSIX path via `abs.slice(cwdPrefixLen)` — O(1) and
+    // avoids the per-entry `path.relative` allocation.
+    cwdPrefixLen: cwd.length + 1,
+    entries: [],
     maxDepth,
     maxEntries,
     recursive,
   };
 
-  await walkDirectory(targetPath, 0, walkState);
-  const { entries } = walkState;
-  return { ok: true, data: { entries } };
+  await walkDirectory(targetPath, 0, state);
+  return { ok: true, data: { entries: state.entries } };
 }
 
 type WalkState = {
   cwd: string;
+  cwdPrefixLen: number;
   entries: DirEntry[];
   maxDepth: number;
   maxEntries: number;
   recursive: boolean;
 };
 
-function reachedWalkLimit(state: WalkState, depth: number): boolean {
-  return state.entries.length >= state.maxEntries || depth > state.maxDepth;
-}
-
 async function readDirEntries(dir: string): Promise<fs.Dirent[]> {
   try {
     return await fs.promises.readdir(dir, { withFileTypes: true });
@@ -46,64 +53,68 @@ async function readDirEntries(dir: string): Promise<fs.Dirent[]> {
   }
 }
 
+function shouldRecurseInto(entry: fs.Dirent, state: WalkState): boolean {
+  return (
+    state.recursive &&
+    entry.isDirectory() &&
+    !entry.isSymbolicLink() &&
+    !entry.name.startsWith(".") &&
+    entry.name !== NODE_MODULES_DIRNAME
+  );
+}
+
+/**
+ * Build a `DirEntry` for `entry` sitting inside `dir`. Returns
+ * `undefined` for symlinks that escape the sandbox.
+ *
+ * `dir` is absolute native-separator, guaranteed to start with
+ * `state.cwd + sep`, so `abs.slice(state.cwdPrefixLen)` yields the
+ * cwd-relative path without a `path.relative` allocation.
+ */
 function toDirEntry(
-  cwd: string,
+  state: WalkState,
   dir: string,
   entry: fs.Dirent
 ): DirEntry | undefined {
-  const relPath = path.relative(cwd, path.join(dir, entry.name));
+  const abs = dir + NATIVE_SEP + entry.name;
+  const relNative = abs.slice(state.cwdPrefixLen);
 
   if (entry.isSymbolicLink()) {
     try {
-      safePath(cwd, relPath);
+      safePath(state.cwd, relNative);
     } catch {
       return;
     }
   }
 
   return {
     name: entry.name,
-    path: relPath,
+    path: normalizePath(relNative),
     type: entry.isDirectory() ? "directory" : "file",
   };
 }
 
-function shouldRecurseInto(entry: fs.Dirent, state: WalkState): boolean {
-  return (
-    state.recursive &&
-    entry.isDirectory() &&
-    !entry.isSymbolicLink() &&
-    !entry.name.startsWith(".") &&
-    entry.name !== "node_modules"
-  );
-}
-
 async function walkDirectory(
   dir: string,
   depth: number,
   state: WalkState
 ): Promise<void> {
-  if (reachedWalkLimit(state, depth)) {
+  if (depth > state.maxDepth || state.entries.length >= state.maxEntries) {
     return;
   }
 
-  const dirEntries = await readDirEntries(dir);
-  for (const entry of dirEntries) {
-    if (reachedWalkLimit(state, depth)) {
+  for (const entry of await readDirEntries(dir)) {
+    if (state.entries.length >= state.maxEntries) {
       return;
     }
-
-    const nextEntry = toDirEntry(state.cwd, dir, entry);
+    const nextEntry = toDirEntry(state, dir, entry);
     if (!nextEntry) {
       continue;
     }
-
     state.entries.push(nextEntry);
-    if (!shouldRecurseInto(entry, state)) {
-      continue;
+    if (shouldRecurseInto(entry, state)) {
+      await walkDirectory(dir + NATIVE_SEP + entry.name, depth + 1, state);
     }
-
-    await walkDirectory(path.join(dir, entry.name), depth + 1, state);
   }
 }
 

src/lib/init/workflow-inputs.ts

@@ -103,9 +103,10 @@ export async function preReadCommonFiles(
   directory: string,
   dirListing: DirEntry[]
 ): Promise<Record<string, string | null>> {
-  const listingPaths = new Set(
-    dirListing.map((entry) => entry.path.replaceAll("\\", "/"))
-  );
+  // `listDir` emits POSIX-normalized paths regardless of host OS,
+  // so `COMMON_CONFIG_FILES` (POSIX) membership checks don't need
+  // any per-path separator translation.
+  const listingPaths = new Set(dirListing.map((entry) => entry.path));
   const toRead = COMMON_CONFIG_FILES.filter((filePath) =>
     listingPaths.has(filePath)
   );

src/lib/sourcemap/inject.ts

@@ -7,6 +7,7 @@
 
 import { readFile, stat } from "node:fs/promises";
 import { resolve as resolvePath } from "node:path";
+import { NODE_MODULES_DIRNAME } from "../constants.js";
 import { walkFiles } from "../scan/index.js";
 import { EXISTING_DEBUGID_RE, injectDebugId } from "./debug-id.js";
 
@@ -110,7 +111,7 @@ async function findCompanionMap(jsPath: string): Promise<string | undefined> {
  *   dropping large JS files would skip debug-ID injection on the
  *   exact bundles users care about most.
  */
-const SOURCEMAP_SKIP_DIRS: readonly string[] = ["node_modules"];
+const SOURCEMAP_SKIP_DIRS: readonly string[] = [NODE_MODULES_DIRNAME];
 
 async function discoverFilePairs(
   dir: string,

src/lib/upgrade.ts

@@ -24,7 +24,7 @@ import {
   KNOWN_CURL_DIRS,
   releaseLock,
 } from "./binary.js";
-import { CLI_VERSION } from "./constants.js";
+import { CLI_VERSION, NODE_MODULES_DIRNAME } from "./constants.js";
 import { getInstallInfo, setInstallInfo } from "./db/install-info.js";
 import type { ReleaseChannel } from "./db/release-channel.js";
 import { attemptDeltaUpgrade, type DeltaResult } from "./delta-upgrade.js";
@@ -237,7 +237,7 @@ export function detectPackageManagerFromPath(): PackageManager | null {
   }
 
   const segments = scriptPath.split(sep);
-  if (!segments.includes("node_modules")) {
+  if (!segments.includes(NODE_MODULES_DIRNAME)) {
     return null;
   }