Function diagnoseDevEnv

src/tools/browser/dev-server.ts:37–68

(cwd: string | undefined, output: string)

 * the user the exact one-line fix. Returns null when the environment looks fine (don't cry wolf).
 */
export function diagnoseDevEnv(cwd: string | undefined, output: string): string | null {
  const notFound = /command not found|: not found|code 127|UNRESOLVED_IMPORT|Could not resolve|cannot find module/i.test(
    output,
  );
  if (!notFound) return null;
  const root = cwd || process.cwd();
  const nm = path.join(root, 'node_modules');
  let detail: string | null = null;
  try {
    if (!fs.existsSync(nm)) {
      detail = 'node_modules does not exist';
    } else {
      const hasBin = fs.existsSync(path.join(nm, '.bin'));
      const pkgs = fs.readdirSync(nm).filter((n) => !n.startsWith('.'));
      // A real install has dozens-to-hundreds of top-level entries and a populated .bin.
      if (!hasBin || pkgs.length <= 3) {
        detail = `node_modules looks incomplete (${pkgs.length} top-level package(s), .bin ${hasBin ? 'present' : 'missing'})`;
      }
    }
  } catch {
    /* if we can't inspect, don't fabricate a diagnosis */
  }
  if (!detail) return null;
  return [
    `[ENV_DEPS_BROKEN] ${detail}.`,
    `This is an ENVIRONMENT problem in the project folder, not a bug in the code — the dependency`,
    `install is broken (usually a stale .npmrc, or an npm/pnpm lockfile mismatch). Re-running install`,
    `from here will keep failing, so do NOT retry the dev server in a loop.`,
    `Tell the user to run this once in their own terminal, then retry the task:`,
    `  rm -rf node_modules package-lock.json pnpm-lock.yaml .npmrc && npm install`,
  ].join('\n');
}

const StartArgs = z.object({
  name: z.string().min(1).max(64).describe('Short id for later reference. e.g. "frontend", "api", "watcher".'),