feat: add TASKMASTER_DOTENV support for custom .env paths

[dwayn]

Add TASKMASTER_DOTENV support for custom .env file paths

Description

This PR adds support for the TASKMASTER_DOTENV environment variable, allowing users to specify a custom path to their .env file instead of being limited to the default project root location. This enables better credential management and cost separation between TaskMaster usage and project runtime environments.

Motivation

Users often want to manage TaskMaster API keys separately from their project's environment variables to:

• Keep TaskMaster credentials isolated from project-specific configuration
• Use shared credential files across multiple projects
• Store sensitive API keys in secure locations outside of project directories
• Manage costs for AI-assisted coding separately from project runtime costs
• Have different credential sets for different MCP sessions

Type of Change

• New feature
• Documentation update
• Tests added

Changes Made

Core Implementation

• Modified scripts/modules/utils.js: Enhanced the resolveEnvVariable function to support TASKMASTER_DOTENV with the following precedence order:
  1. session.env[key] (direct variable lookup in MCP session)
  2. Custom .env file from session.env.TASKMASTER_DOTENV (MCP session configuration)
  3. Custom .env file from process.env.TASKMASTER_DOTENV (shell environment)
  4. Default .env file at project root
  5. process.env[key] (fallback to system environment)

Comprehensive Test Coverage

• Added 11 comprehensive tests in tests/unit/utils.test.js covering:
  • ✅ Priority order testing: Ensures correct precedence across all sources
  • ✅ File resolution testing: Custom paths from both session and process env
  • ✅ Error handling: Non-existent files, read errors, invalid paths
  • ✅ Edge cases: Empty/whitespace values, relative paths, fallback scenarios
  • ✅ Mock integration: Proper fs/path mocking following project patterns

Documentation Updates

• Updated docs/configuration.md: Added comprehensive documentation including:
  • Explanation of the new TASKMASTER_DOTENV feature in the main configuration section
  • Separate sections for CLI and MCP usage with practical examples
  • Complete MCP configuration examples for both .cursor/mcp.json and VS Code .vscode/mcp.json
  • Use cases and benefits of custom .env file locations

Usage Examples

CLI Usage

# Set custom .env file location
export TASKMASTER_DOTENV=/home/user/.config/taskmaster/.env
task-master list

# Or inline
TASKMASTER_DOTENV=/path/to/custom/.env task-master init

MCP Usage

{
  "mcpServers": {
    "taskmaster-ai": {
      "command": "npx",
      "args": ["-y", "--package=task-master-ai", "task-master-ai"],
      "env": {
        "TASKMASTER_DOTENV": "/path/to/your/custom/.env"
      }
    }
  }
}

Testing

• I have tested this locally with both CLI and MCP scenarios
• All existing tests pass (322 total, 311 passed, 11 skipped)
• Added comprehensive new tests (11 tests covering all scenarios)
• Function follows existing patterns in the codebase
• Verified backward compatibility - existing behavior unchanged when TASKMASTER_DOTENV is not set
• Tested with both absolute and relative paths
• Verified proper error handling for invalid paths
• Code formatting passes (npm run format-check)

Changeset

• I have created a changeset (minor bump for new feature)

Backward Compatibility

✅ Fully backward compatible - When TASKMASTER_DOTENV is not set, the system behaves exactly as before, using the project root .env file.

Additional Notes

This implementation provides a clean, flexible solution for credential management that works seamlessly across both CLI and MCP usage patterns. The precedence order ensures that MCP session configurations take priority over system environment
variables, allowing for fine-grained control in multi-session scenarios.

The comprehensive test suite ensures robustness across all edge cases and follows the project's established testing patterns, providing confidence in the feature's reliability.

[changeset-bot]

🦋 Changeset detected

Latest commit: e5e5721

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
task-master-ai	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[Crunchyman-ralph]

small nit pick then ready to merge

[Crunchyman-ralph]

why not also use:
require('dotenv').config({ path: '/custom/path/to/.env' })

From:
https://www.npmjs.com/package/dotenv

[Crunchyman-ralph]

Thanks for this, custom .env paths is a practical feature.

Unfortunately it's been sitting with merge conflicts for a long time and the codebase has moved on. Closing this one, but the concept is solid. If you want to reopen against current main, we'd be happy to review. Appreciate your time!