An AI-powered task-management system you can drop into Cursor, Lovable, Windsurf, Roo, and others.
JavaScript aicursorcursor-aicursorailovablelovable-devroocodetask-managertaskstasks-listwindsurfwindsurf-ai
feat(project-root): enhance project root detection with boundary markers (#1545)
Ralph Khreisha0007a357530
diff --git a/.changeset/lazy-lies-argue.md b/.changeset/lazy-lies-argue.mdnew file mode 100644index 00000000..979b7e1e--- /dev/null+++ b/.changeset/lazy-lies-argue.md@@ -0,0 +1,9 @@+---+"task-master-ai": patch+---++Smarter project root detection with boundary markers++- Prevents Task Master from incorrectly detecting `.taskmaster` folders in your home directory when working inside a different project+- Now stops at project boundaries (`.git`, `package.json`, lock files) instead of searching all the way up to the filesystem root+- Adds support for monorepo markers (`lerna.json`, `nx.json`, `turbo.json`) and additional lock files (`bun.lockb`, `deno.lock`)diff --git a/apps/mcp/package.json b/apps/mcp/package.jsonindex 2b746be2..676ee584 100644--- a/apps/mcp/package.json+++ b/apps/mcp/package.json@@ -24,7 +24,8 @@"dependencies": {"@tm/core": "*","fastmcp": "^3.23.0",- "zod": "^4.1.11"+ "zod": "^4.1.11",+ "dotenv": "^16.6.1"},"devDependencies": {"@biomejs/biome": "^1.9.4",diff --git a/apps/mcp/src/shared/utils.ts b/apps/mcp/src/shared/utils.tsindex 0c2fd735..141ad537 100644--- a/apps/mcp/src/shared/utils.ts+++ b/apps/mcp/src/shared/utils.ts@@ -2,6 +2,7 @@* Shared utilities for MCP tools*/+import dotenv from 'dotenv';import fs from 'node:fs';import path from 'node:path';import {@@ -395,6 +396,13 @@ export function withToolContext<TArgs extends { projectRoot?: string }>(args: TArgs & { projectRoot: string },context: Context<undefined>) => {+ // Load project .env if it exists (won't overwrite MCP-provided env vars)+ // This ensures project-specific env vars are available to tool execution+ const envPath = path.join(args.projectRoot, '.env');+ if (fs.existsSync(envPath)) {+ dotenv.config({ path: envPath });+ }+// Create tmCore instanceconst tmCore = await createTmCore({projectPath: args.projectRoot,diff --git a/package-lock.json b/package-lock.jsonindex 18851057..d4eb1503 100644--- a/package-lock.json+++ b/package-lock.json@@ -1,12 +1,12 @@{"name": "task-master-ai",- "version": "0.39.0",+ "version": "0.40.0-rc.1","lockfileVersion": 3,"requires": true,"packages": {"": {"name": "task-master-ai",- "version": "0.39.0",+ "version": "0.40.0-rc.1","license": "MIT WITH Commons-Clause","workspaces": ["apps/*",@@ -1850,7 +1850,7 @@"react-dom": "^19.0.0","tailwind-merge": "^3.3.1","tailwindcss": "4.1.11",- "task-master-ai": "*",+ "task-master-ai": "0.40.0-rc.1","typescript": "^5.9.2"},"engines": {@@ -1971,6 +1971,7 @@"license": "MIT","dependencies": {"@tm/core": "*",+ "dotenv": "^16.6.1","fastmcp": "^3.23.0","zod": "^4.1.11"},diff --git a/packages/tm-core/src/common/utils/project-root-finder.test.ts b/packages/tm-core/src/common/utils/project-root-finder.test.tsnew file mode 100644index 00000000..52c29628--- /dev/null+++ b/packages/tm-core/src/common/utils/project-root-finder.test.ts@@ -0,0 +1,268 @@+/**+ * @fileoverview Integration tests for project root detection+ *+ * These tests verify real-world scenarios for project root detection,+ * particularly edge cases around:+ * - Empty directories (tm init scenario)+ * - .taskmaster in home/parent directories that should be ignored+ * - Monorepo detection+ */++import fs from 'node:fs';+import os from 'node:os';+import path from 'node:path';+import { afterEach, beforeEach, describe, expect, it } from 'vitest';+import { findProjectRoot } from './project-root-finder.js';++describe('findProjectRoot - Integration Tests', () => {+ let tempDir: string;++ beforeEach(() => {+ // Create a temporary directory structure for testing+ tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'tm-integration-test-'));+ });++ afterEach(() => {+ // Clean up temp directory+ if (fs.existsSync(tempDir)) {+ fs.rmSync(tempDir, { recursive: true, force: true });+ }+ });++ describe('Empty directory scenarios (tm init)', () => {+ it('should find .taskmaster in immediate parent (depth=1) even without boundary marker', () => {+ // Scenario: User is in a subdirectory of a project that only has .taskmaster+ // (no .git or package.json). This is a valid use case for projects where+ // user ran `tm init` but not `git init`.+ //+ // Structure:+ // /project/.taskmaster+ // /project/src/ (start here)+ //+ // NOTE: For `tm init` command specifically, the command should use+ // process.cwd() directly instead of findProjectRoot() to avoid+ // finding a stray .taskmaster in a parent directory.++ const projectDir = tempDir;+ const srcDir = path.join(projectDir, 'src');++ fs.mkdirSync(path.join(projectDir, '.taskmaster'));+ fs.mkdirSync(srcDir);++ const result = findProjectRoot(srcDir);++ // Immediate parent (depth=1) is trusted even without boundary marker+ expect(result).toBe(projectDir);+ });++ it('should return startDir when running from completely empty directory', () => {+ // Scenario: User runs `tm init` in a brand new, completely empty directory+ // No markers anywhere in the tree+ //+ // Structure:+ // /tmp/test/empty-project/ (empty)++ const emptyProjectDir = path.join(tempDir, 'empty-project');+ fs.mkdirSync(emptyProjectDir);++ const result = findProjectRoot(emptyProjectDir);++ // Should return the empty directory itself+ expect(result).toBe(emptyProjectDir);+ });++ it('should return startDir when no boundary markers exist but .taskmaster exists in distant parent', () => {+ // Scenario: Deep directory structure with .taskmaster only at top level+ // No boundary markers (.git, package.json, etc.) anywhere+ //+ // Structure:+ // /tmp/home/.taskmaster (should be IGNORED - too far up)+ // /tmp/home/code/projects/my-app/ (empty - no markers)++ const homeDir = tempDir;+ const deepProjectDir = path.join(homeDir, 'code', 'projects', 'my-app');++ fs.mkdirSync(path.join(homeDir, '.taskmaster'));+ fs.mkdirSync(deepProjectDir, { recursive: true });++ const result = findProjectRoot(deepProjectDir);++ // Should return the deep directory, not home+ expect(result).toBe(deepProjectDir);+ });+ });++ describe('Project with boundary markers', () => {+ it('should find .taskmaster when at same level as .git', () => {+ // Scenario: Normal project setup with both .taskmaster and .git+ //+ // Structure:+ // /tmp/project/.taskmaster+ // /tmp/project/.git++ const projectDir = tempDir;++ fs.mkdirSync(path.join(projectDir, '.taskmaster'));+ fs.mkdirSync(path.join(projectDir, '.git'));++ const result = findProjectRoot(projectDir);++ expect(result).toBe(projectDir);+ });++ it('should find .taskmaster in parent when subdirectory has no markers', () => {+ // Scenario: Running from a subdirectory of an initialized project+ //+ // Structure:+ // /tmp/project/.taskmaster+ // /tmp/project/.git+ // /tmp/project/src/components/ (no markers)++ const projectDir = tempDir;+ const srcDir = path.join(projectDir, 'src', 'components');++ fs.mkdirSync(path.join(projectDir, '.taskmaster'));+ fs.mkdirSync(path.join(projectDir, '.git'));+ fs.mkdirSync(srcDir, { recursive: true });++ const result = findProjectRoot(srcDir);++ expect(result).toBe(projectDir);+ });++ it('should stop at .git and NOT find .taskmaster beyond it', () => {+ // Scenario: Project has .git but no .taskmaster, parent has .taskmaster+ // Should use project with .git, not parent with .taskmaster+ //+ // Structure:+ // /tmp/home/.taskmaster (should be IGNORED)+ // /tmp/home/my-project/.git (boundary marker)++ const homeDir = tempDir;+ const projectDir = path.join(homeDir, 'my-project');++ fs.mkdirSync(path.join(homeDir, '.taskmaster'));+ fs.mkdirSync(path.join(projectDir, '.git'), { recursive: true });++ const result = findProjectRoot(projectDir);++ expect(result).toBe(projectDir);+ });++ it('should stop at package.json and NOT find .taskmaster beyond it', () => {+ // Scenario: JS project with package.json but no .taskmaster+ //+ // Structure:+ // /tmp/home/.taskmaster (should be IGNORED)+ // /tmp/home/my-project/package.json (boundary)++ const homeDir = tempDir;+ const projectDir = path.join(homeDir, 'my-project');++ fs.mkdirSync(path.join(homeDir, '.taskmaster'));+ fs.mkdirSync(projectDir);+ fs.writeFileSync(path.join(projectDir, 'package.json'), '{}');++ const result = findProjectRoot(projectDir);++ expect(result).toBe(projectDir);+ });+ });++ describe('Monorepo scenarios', () => {+ it('should find monorepo root .taskmaster from package subdirectory', () => {+ // Scenario: Monorepo with .taskmaster at root, packages without their own markers+ //+ // Structure:+ // /tmp/monorepo/.taskmaster+ // /tmp/monorepo/.git+ // /tmp/monorepo/packages/my-package/src/++ const monorepoRoot = tempDir;+ const packageSrcDir = path.join(+ monorepoRoot,+ 'packages',+ 'my-package',+ 'src'+ );++ fs.mkdirSync(path.join(monorepoRoot, '.taskmaster'));+ fs.mkdirSync(path.join(monorepoRoot, '.git'));+ fs.mkdirSync(packageSrcDir, { recursive: true });++ const result = findProjectRoot(packageSrcDir);++ expect(result).toBe(monorepoRoot);+ });++ it('should return package root when package has its own boundary marker', () => {+ // Scenario: Monorepo where individual package has its own package.json+ // Package should be treated as its own project+ //+ // Structure:+ // /tmp/monorepo/.taskmaster+ // /tmp/monorepo/packages/my-package/package.json (boundary)++ const monorepoRoot = tempDir;+ const packageDir = path.join(monorepoRoot, 'packages', 'my-package');++ fs.mkdirSync(path.join(monorepoRoot, '.taskmaster'));+ fs.mkdirSync(packageDir, { recursive: true });+ fs.writeFileSync(path.join(packageDir, 'package.json'), '{}');++ const result = findProjectRoot(packageDir);++ // Package has its own boundary, so it should be returned+ expect(result).toBe(packageDir);+ });++ it('should return package root when package has its own .taskmaster', () => {+ // Scenario: Nested Task Master initialization+ //+ // Structure:+ // /tmp/monorepo/.taskmaster+ // /tmp/monorepo/packages/my-package/.taskmaster++ const monorepoRoot = tempDir;+ const packageDir = path.join(monorepoRoot, 'packages', 'my-package');++ fs.mkdirSync(path.join(monorepoRoot, '.taskmaster'));+ fs.mkdirSync(path.join(packageDir, '.taskmaster'), { recursive: true });++ const result = findProjectRoot(packageDir);++ // Package has its own .taskmaster, so it should be returned+ expect(result).toBe(packageDir);+ });+ });++ describe('Environment variable loading context', () => {+ it('should document that .env loading should use process.cwd(), not findProjectRoot()', () => {+ // IMPORTANT: For .env loading (e.g., TM_BASE_DOMAIN for auth),+ // the code should use process.cwd() directly, NOT findProjectRoot().+ //+ // findProjectRoot() is designed to find the .taskmaster directory+ // for task storage. It will traverse up to find .taskmaster in parent+ // directories when appropriate.+ //+ // For environment variables, we want to load from WHERE the user+ // is running the command, not where .taskmaster is located.+ //+ // This test documents this design decision and verifies findProjectRoot+ // behavior when .taskmaster is in immediate parent (depth=1).++ const projectDir = tempDir;+ const subDir = path.join(projectDir, 'subdir');++ fs.mkdirSync(path.join(projectDir, '.taskmaster'));+ fs.mkdirSync(subDir);++ const result = findProjectRoot(subDir);++ // findProjectRoot WILL find parent's .taskmaster (depth=1 is trusted)+ // This is correct for task storage - we want to use the parent's tasks.json+ // For .env loading, callers should use process.cwd() instead+ expect(result).toBe(projectDir);+ });+ });+});diff --git a/packages/tm-core/src/common/utils/project-root-finder.ts b/packages/tm-core/src/common/utils/project-root-finder.tsindex 58926043..2720e771 100644--- a/packages/tm-core/src/common/utils/project-root-finder.ts+++ b/packages/tm-core/src/common/utils/project-root-finder.ts@@ -1,8 +1,3 @@-/**- * @fileoverview Project root detection utilities- * Provides functionality to locate project roots by searching for marker files/directories- */-import fs from 'node:fs';import path from 'node:path';import {@@ -11,9 +6,6 @@ import {TASKMASTER_PROJECT_MARKERS} from '../constants/paths.js';-/**- * Check if a marker file/directory exists at the given path- */function markerExists(dir: string, marker: string): boolean {try {return fs.existsSync(path.join(dir, marker));@@ -22,170 +14,101 @@ function markerExists(dir: string, marker: string): boolean {}}-/**- * Check if any of the given markers exist in a directory- */function hasAnyMarker(dir: string, markers: readonly string[]): boolean {return markers.some((marker) => markerExists(dir, marker));}/**- * Find the project root directory by looking for project markers- * Traverses upwards from startDir until a project marker is found or filesystem root is reached- * Limited to 50 parent directory levels to prevent excessive traversal- *- * Strategy:- * 1. PASS 1: Search for .taskmaster markers, but STOP at project boundaries- * - If .taskmaster found, return that directory- * - If a project boundary (package.json, .git, lock files) is found WITHOUT .taskmaster,- * stop searching further up (prevents finding .taskmaster in home directory)- * 2. PASS 2: If no .taskmaster found, search for other project markers- *- * This ensures:- * - .taskmaster in a parent directory takes precedence (within project boundary)- * - .taskmaster outside the project boundary (e.g., home dir) is NOT returned+ * Find the project root by traversing upward from startDir looking for project markers.*- * @param startDir - Directory to start searching from (defaults to process.cwd())- * @returns Project root path (falls back to startDir if no markers found)- *- * @example- * ```typescript- * // In a monorepo structure:- * // /project/.taskmaster- * // /project/packages/my-package/.git- * // When called from /project/packages/my-package:- * const root = findProjectRoot(); // Returns /project (not /project/packages/my-package)- *- * // When .taskmaster is outside project boundary:- * // /home/user/.taskmaster (should be ignored!)- * // /home/user/code/myproject/package.json- * // When called from /home/user/code/myproject:- * const root = findProjectRoot(); // Returns /home/user/code/myproject (NOT /home/user)- * ```+ * Search strategy prevents false matches from stray .taskmaster dirs (e.g., in home):+ * 1. If startDir has .taskmaster or a boundary marker (.git, package.json), return immediately+ * 2. Search parents for .taskmaster anchored by a boundary marker (or 1 level up without boundary)+ * 3. Fall back to searching for other project markers (pyproject.toml, Cargo.toml, etc.)+ * 4. If nothing found, return startDir (supports `tm init` in empty directories)*/export function findProjectRoot(startDir: string = process.cwd()): string {let currentDir = path.resolve(startDir);const rootDir = path.parse(currentDir).root;- const maxDepth = 50; // Reasonable limit to prevent infinite loops+ const maxDepth = 50;let depth = 0;-- // Track if we've seen a project boundary - we'll stop searching for .taskmaster beyond itlet projectBoundaryDir: string | null = null;- // FIRST PASS: Search for Task Master markers, but respect project boundaries- // A project boundary is a directory containing .git, package.json, lock files, etc.- // If we find a boundary without .taskmaster, we stop searching further up- let searchDir = currentDir;- depth = 0;+ // Check startDir first - if it has .taskmaster or a boundary marker, we're done+ if (hasAnyMarker(currentDir, TASKMASTER_PROJECT_MARKERS)) {+ return currentDir;+ }+ if (hasAnyMarker(currentDir, PROJECT_BOUNDARY_MARKERS)) {+ return currentDir;+ }++ // Search parent directories for .taskmaster+ let searchDir = path.dirname(currentDir);+ depth = 1;while (depth < maxDepth) {- // First, check for Task Master markers in this directory- for (const marker of TASKMASTER_PROJECT_MARKERS) {- if (markerExists(searchDir, marker)) {- // Found a Task Master marker - this is our project root+ const hasTaskmaster = hasAnyMarker(searchDir, TASKMASTER_PROJECT_MARKERS);+ const hasBoundary = hasAnyMarker(searchDir, PROJECT_BOUNDARY_MARKERS);++ if (hasTaskmaster) {+ // Accept .taskmaster if anchored by boundary or only 1 level up+ if (hasBoundary || depth === 1) {return searchDir;}+ // Distant .taskmaster without boundary is likely stray (e.g., home dir) - skip it}- // Check if this directory is a project boundary- // (has markers like .git, package.json, lock files, etc.)- if (hasAnyMarker(searchDir, PROJECT_BOUNDARY_MARKERS)) {- // This is a project boundary - record it and STOP looking for .taskmaster- // beyond this point. The .taskmaster in home directory should NOT be found- // when the user is inside a different project.+ if (hasBoundary && !hasTaskmaster) {+ // Hit project boundary without .taskmaster - stop searching upwardprojectBoundaryDir = searchDir;- break; // Stop Pass 1 - don't look for .taskmaster beyond this boundary- }-- // If we're at root, stop after checking it- if (searchDir === rootDir) {break;}- // Move up one directory level- const parentDir = path.dirname(searchDir);+ if (searchDir === rootDir) break;- // Safety check: if dirname returns the same path, we've hit the root- if (parentDir === searchDir) {- break;- }+ const parentDir = path.dirname(searchDir);+ if (parentDir === searchDir) break;searchDir = parentDir;depth++;}- // SECOND PASS: No Task Master markers found within project boundary- // Now search for other project markers starting from the original directory- // If we found a project boundary in Pass 1, start from there (it will match immediately)+ // No .taskmaster found - search for other project markerscurrentDir = projectBoundaryDir || path.resolve(startDir);depth = 0;while (depth < maxDepth) {- for (const marker of OTHER_PROJECT_MARKERS) {- if (markerExists(currentDir, marker)) {- // Found another project marker - return this as project root- return currentDir;- }+ if (hasAnyMarker(currentDir, OTHER_PROJECT_MARKERS)) {+ return currentDir;}- // If we're at root, stop after checking it- if (currentDir === rootDir) {- break;- }+ if (currentDir === rootDir) break;- // Move up one directory levelconst parentDir = path.dirname(currentDir);-- // Safety check: if dirname returns the same path, we've hit the root- if (parentDir === currentDir) {- break;- }+ if (parentDir === currentDir) break;currentDir = parentDir;depth++;}- // Fallback to startDir if no project root found- // This handles empty repos or directories with no recognized project markers- // (e.g., a repo with just a .env file should still use that directory as root)return path.resolve(startDir);}/**- * Normalize project root to ensure it doesn't end with .taskmaster- * This prevents double .taskmaster paths when using constants that include .taskmaster- *- * @param projectRoot - The project root path to normalize- * @returns Normalized project root path- *- * @example- * ```typescript- * normalizeProjectRoot('/project/.taskmaster'); // Returns '/project'- * normalizeProjectRoot('/project'); // Returns '/project'- * normalizeProjectRoot('/project/.taskmaster/tasks'); // Returns '/project'- * ```+ * Strip .taskmaster (and anything after it) from a path.+ * Prevents double .taskmaster paths when combining with constants that include .taskmaster.*/export function normalizeProjectRoot(projectRoot: string | null | undefined): string {- if (!projectRoot) return projectRoot || '';-- // Ensure it's a string- const projectRootStr = String(projectRoot);-- // Split the path into segments- const segments = projectRootStr.split(path.sep);+ if (!projectRoot) return '';- // Find the index of .taskmaster segment- const taskmasterIndex = segments.findIndex(- (segment) => segment === '.taskmaster'- );+ const segments = String(projectRoot).split(path.sep);+ const taskmasterIndex = segments.findIndex((s) => s === '.taskmaster');if (taskmasterIndex !== -1) {- // If .taskmaster is found, return everything up to but not including .taskmaster- const normalizedSegments = segments.slice(0, taskmasterIndex);- return normalizedSegments.join(path.sep) || path.sep;+ return segments.slice(0, taskmasterIndex).join(path.sep) || path.sep;}- return projectRootStr;+ return String(projectRoot);}diff --git a/tests/unit/task-master.test.js b/tests/unit/task-master.test.jsindex 6570eb98..a7b43237 100644--- a/tests/unit/task-master.test.js+++ b/tests/unit/task-master.test.js@@ -93,9 +93,12 @@ describe('initTaskMaster', () => {});test('should find project root from deeply nested subdirectory', () => {- // Arrange - Create .taskmaster directory in temp dir+ // Arrange - Create .taskmaster directory and a boundary marker in temp dir+ // The boundary marker (.git) anchors .taskmaster to prevent false matches+ // from stray .taskmaster dirs (e.g., in home directory)const taskMasterDir = path.join(tempDir, TASKMASTER_DIR);fs.mkdirSync(taskMasterDir, { recursive: true });+ fs.mkdirSync(path.join(tempDir, '.git'), { recursive: true });// Create deeply nested subdirectory and change to itconst deepDir = path.join(tempDir, 'src', 'components', 'ui');