This is page 31 of 50. Use http://codebase.md/eyaltoledano/claude-task-master?page={x} to view the full context.
# Directory Structure
```
├── .changeset
│ ├── config.json
│ └── README.md
├── .claude
│ ├── commands
│ │ └── dedupe.md
│ └── TM_COMMANDS_GUIDE.md
├── .claude-plugin
│ └── marketplace.json
├── .coderabbit.yaml
├── .cursor
│ ├── mcp.json
│ └── rules
│ ├── ai_providers.mdc
│ ├── ai_services.mdc
│ ├── architecture.mdc
│ ├── changeset.mdc
│ ├── commands.mdc
│ ├── context_gathering.mdc
│ ├── cursor_rules.mdc
│ ├── dependencies.mdc
│ ├── dev_workflow.mdc
│ ├── git_workflow.mdc
│ ├── glossary.mdc
│ ├── mcp.mdc
│ ├── new_features.mdc
│ ├── self_improve.mdc
│ ├── tags.mdc
│ ├── taskmaster.mdc
│ ├── tasks.mdc
│ ├── telemetry.mdc
│ ├── test_workflow.mdc
│ ├── tests.mdc
│ ├── ui.mdc
│ └── utilities.mdc
├── .cursorignore
├── .env.example
├── .github
│ ├── ISSUE_TEMPLATE
│ │ ├── bug_report.md
│ │ ├── enhancements---feature-requests.md
│ │ └── feedback.md
│ ├── PULL_REQUEST_TEMPLATE
│ │ ├── bugfix.md
│ │ ├── config.yml
│ │ ├── feature.md
│ │ └── integration.md
│ ├── PULL_REQUEST_TEMPLATE.md
│ ├── scripts
│ │ ├── auto-close-duplicates.mjs
│ │ ├── backfill-duplicate-comments.mjs
│ │ ├── check-pre-release-mode.mjs
│ │ ├── parse-metrics.mjs
│ │ ├── release.mjs
│ │ ├── tag-extension.mjs
│ │ ├── utils.mjs
│ │ └── validate-changesets.mjs
│ └── workflows
│ ├── auto-close-duplicates.yml
│ ├── backfill-duplicate-comments.yml
│ ├── ci.yml
│ ├── claude-dedupe-issues.yml
│ ├── claude-docs-trigger.yml
│ ├── claude-docs-updater.yml
│ ├── claude-issue-triage.yml
│ ├── claude.yml
│ ├── extension-ci.yml
│ ├── extension-release.yml
│ ├── log-issue-events.yml
│ ├── pre-release.yml
│ ├── release-check.yml
│ ├── release.yml
│ ├── update-models-md.yml
│ └── weekly-metrics-discord.yml
├── .gitignore
├── .kiro
│ ├── hooks
│ │ ├── tm-code-change-task-tracker.kiro.hook
│ │ ├── tm-complexity-analyzer.kiro.hook
│ │ ├── tm-daily-standup-assistant.kiro.hook
│ │ ├── tm-git-commit-task-linker.kiro.hook
│ │ ├── tm-pr-readiness-checker.kiro.hook
│ │ ├── tm-task-dependency-auto-progression.kiro.hook
│ │ └── tm-test-success-task-completer.kiro.hook
│ ├── settings
│ │ └── mcp.json
│ └── steering
│ ├── dev_workflow.md
│ ├── kiro_rules.md
│ ├── self_improve.md
│ ├── taskmaster_hooks_workflow.md
│ └── taskmaster.md
├── .manypkg.json
├── .mcp.json
├── .npmignore
├── .nvmrc
├── .taskmaster
│ ├── CLAUDE.md
│ ├── config.json
│ ├── docs
│ │ ├── autonomous-tdd-git-workflow.md
│ │ ├── MIGRATION-ROADMAP.md
│ │ ├── prd-tm-start.txt
│ │ ├── prd.txt
│ │ ├── README.md
│ │ ├── research
│ │ │ ├── 2025-06-14_how-can-i-improve-the-scope-up-and-scope-down-comm.md
│ │ │ ├── 2025-06-14_should-i-be-using-any-specific-libraries-for-this.md
│ │ │ ├── 2025-06-14_test-save-functionality.md
│ │ │ ├── 2025-06-14_test-the-fix-for-duplicate-saves-final-test.md
│ │ │ └── 2025-08-01_do-we-need-to-add-new-commands-or-can-we-just-weap.md
│ │ ├── task-template-importing-prd.txt
│ │ ├── tdd-workflow-phase-0-spike.md
│ │ ├── tdd-workflow-phase-1-core-rails.md
│ │ ├── tdd-workflow-phase-1-orchestrator.md
│ │ ├── tdd-workflow-phase-2-pr-resumability.md
│ │ ├── tdd-workflow-phase-3-extensibility-guardrails.md
│ │ ├── test-prd.txt
│ │ └── tm-core-phase-1.txt
│ ├── reports
│ │ ├── task-complexity-report_autonomous-tdd-git-workflow.json
│ │ ├── task-complexity-report_cc-kiro-hooks.json
│ │ ├── task-complexity-report_tdd-phase-1-core-rails.json
│ │ ├── task-complexity-report_tdd-workflow-phase-0.json
│ │ ├── task-complexity-report_test-prd-tag.json
│ │ ├── task-complexity-report_tm-core-phase-1.json
│ │ ├── task-complexity-report.json
│ │ └── tm-core-complexity.json
│ ├── state.json
│ ├── tasks
│ │ ├── task_001_tm-start.txt
│ │ ├── task_002_tm-start.txt
│ │ ├── task_003_tm-start.txt
│ │ ├── task_004_tm-start.txt
│ │ ├── task_007_tm-start.txt
│ │ └── tasks.json
│ └── templates
│ ├── example_prd_rpg.md
│ └── example_prd.md
├── .vscode
│ ├── extensions.json
│ └── settings.json
├── apps
│ ├── cli
│ │ ├── CHANGELOG.md
│ │ ├── package.json
│ │ ├── src
│ │ │ ├── command-registry.ts
│ │ │ ├── commands
│ │ │ │ ├── auth.command.ts
│ │ │ │ ├── autopilot
│ │ │ │ │ ├── abort.command.ts
│ │ │ │ │ ├── commit.command.ts
│ │ │ │ │ ├── complete.command.ts
│ │ │ │ │ ├── index.ts
│ │ │ │ │ ├── next.command.ts
│ │ │ │ │ ├── resume.command.ts
│ │ │ │ │ ├── shared.ts
│ │ │ │ │ ├── start.command.ts
│ │ │ │ │ └── status.command.ts
│ │ │ │ ├── briefs.command.ts
│ │ │ │ ├── context.command.ts
│ │ │ │ ├── export.command.ts
│ │ │ │ ├── list.command.ts
│ │ │ │ ├── models
│ │ │ │ │ ├── custom-providers.ts
│ │ │ │ │ ├── fetchers.ts
│ │ │ │ │ ├── index.ts
│ │ │ │ │ ├── prompts.ts
│ │ │ │ │ ├── setup.ts
│ │ │ │ │ └── types.ts
│ │ │ │ ├── next.command.ts
│ │ │ │ ├── set-status.command.ts
│ │ │ │ ├── show.command.ts
│ │ │ │ ├── start.command.ts
│ │ │ │ └── tags.command.ts
│ │ │ ├── index.ts
│ │ │ ├── lib
│ │ │ │ └── model-management.ts
│ │ │ ├── types
│ │ │ │ └── tag-management.d.ts
│ │ │ ├── ui
│ │ │ │ ├── components
│ │ │ │ │ ├── cardBox.component.ts
│ │ │ │ │ ├── dashboard.component.ts
│ │ │ │ │ ├── header.component.ts
│ │ │ │ │ ├── index.ts
│ │ │ │ │ ├── next-task.component.ts
│ │ │ │ │ ├── suggested-steps.component.ts
│ │ │ │ │ └── task-detail.component.ts
│ │ │ │ ├── display
│ │ │ │ │ ├── messages.ts
│ │ │ │ │ └── tables.ts
│ │ │ │ ├── formatters
│ │ │ │ │ ├── complexity-formatters.ts
│ │ │ │ │ ├── dependency-formatters.ts
│ │ │ │ │ ├── priority-formatters.ts
│ │ │ │ │ ├── status-formatters.spec.ts
│ │ │ │ │ └── status-formatters.ts
│ │ │ │ ├── index.ts
│ │ │ │ └── layout
│ │ │ │ ├── helpers.spec.ts
│ │ │ │ └── helpers.ts
│ │ │ └── utils
│ │ │ ├── auth-helpers.ts
│ │ │ ├── auto-update.ts
│ │ │ ├── brief-selection.ts
│ │ │ ├── display-helpers.ts
│ │ │ ├── error-handler.ts
│ │ │ ├── index.ts
│ │ │ ├── project-root.ts
│ │ │ ├── task-status.ts
│ │ │ ├── ui.spec.ts
│ │ │ └── ui.ts
│ │ ├── tests
│ │ │ ├── integration
│ │ │ │ └── commands
│ │ │ │ └── autopilot
│ │ │ │ └── workflow.test.ts
│ │ │ └── unit
│ │ │ ├── commands
│ │ │ │ ├── autopilot
│ │ │ │ │ └── shared.test.ts
│ │ │ │ ├── list.command.spec.ts
│ │ │ │ └── show.command.spec.ts
│ │ │ └── ui
│ │ │ └── dashboard.component.spec.ts
│ │ ├── tsconfig.json
│ │ └── vitest.config.ts
│ ├── docs
│ │ ├── archive
│ │ │ ├── ai-client-utils-example.mdx
│ │ │ ├── ai-development-workflow.mdx
│ │ │ ├── command-reference.mdx
│ │ │ ├── configuration.mdx
│ │ │ ├── cursor-setup.mdx
│ │ │ ├── examples.mdx
│ │ │ └── Installation.mdx
│ │ ├── best-practices
│ │ │ ├── advanced-tasks.mdx
│ │ │ ├── configuration-advanced.mdx
│ │ │ └── index.mdx
│ │ ├── capabilities
│ │ │ ├── cli-root-commands.mdx
│ │ │ ├── index.mdx
│ │ │ ├── mcp.mdx
│ │ │ ├── rpg-method.mdx
│ │ │ └── task-structure.mdx
│ │ ├── CHANGELOG.md
│ │ ├── command-reference.mdx
│ │ ├── configuration.mdx
│ │ ├── docs.json
│ │ ├── favicon.svg
│ │ ├── getting-started
│ │ │ ├── api-keys.mdx
│ │ │ ├── contribute.mdx
│ │ │ ├── faq.mdx
│ │ │ └── quick-start
│ │ │ ├── configuration-quick.mdx
│ │ │ ├── execute-quick.mdx
│ │ │ ├── installation.mdx
│ │ │ ├── moving-forward.mdx
│ │ │ ├── prd-quick.mdx
│ │ │ ├── quick-start.mdx
│ │ │ ├── requirements.mdx
│ │ │ ├── rules-quick.mdx
│ │ │ └── tasks-quick.mdx
│ │ ├── introduction.mdx
│ │ ├── licensing.md
│ │ ├── logo
│ │ │ ├── dark.svg
│ │ │ ├── light.svg
│ │ │ └── task-master-logo.png
│ │ ├── package.json
│ │ ├── README.md
│ │ ├── style.css
│ │ ├── tdd-workflow
│ │ │ ├── ai-agent-integration.mdx
│ │ │ └── quickstart.mdx
│ │ ├── vercel.json
│ │ └── whats-new.mdx
│ ├── extension
│ │ ├── .vscodeignore
│ │ ├── assets
│ │ │ ├── banner.png
│ │ │ ├── icon-dark.svg
│ │ │ ├── icon-light.svg
│ │ │ ├── icon.png
│ │ │ ├── screenshots
│ │ │ │ ├── kanban-board.png
│ │ │ │ └── task-details.png
│ │ │ └── sidebar-icon.svg
│ │ ├── CHANGELOG.md
│ │ ├── components.json
│ │ ├── docs
│ │ │ ├── extension-CI-setup.md
│ │ │ └── extension-development-guide.md
│ │ ├── esbuild.js
│ │ ├── LICENSE
│ │ ├── package.json
│ │ ├── package.mjs
│ │ ├── package.publish.json
│ │ ├── README.md
│ │ ├── src
│ │ │ ├── components
│ │ │ │ ├── ConfigView.tsx
│ │ │ │ ├── constants.ts
│ │ │ │ ├── TaskDetails
│ │ │ │ │ ├── AIActionsSection.tsx
│ │ │ │ │ ├── DetailsSection.tsx
│ │ │ │ │ ├── PriorityBadge.tsx
│ │ │ │ │ ├── SubtasksSection.tsx
│ │ │ │ │ ├── TaskMetadataSidebar.tsx
│ │ │ │ │ └── useTaskDetails.ts
│ │ │ │ ├── TaskDetailsView.tsx
│ │ │ │ ├── TaskMasterLogo.tsx
│ │ │ │ └── ui
│ │ │ │ ├── badge.tsx
│ │ │ │ ├── breadcrumb.tsx
│ │ │ │ ├── button.tsx
│ │ │ │ ├── card.tsx
│ │ │ │ ├── collapsible.tsx
│ │ │ │ ├── CollapsibleSection.tsx
│ │ │ │ ├── dropdown-menu.tsx
│ │ │ │ ├── label.tsx
│ │ │ │ ├── scroll-area.tsx
│ │ │ │ ├── separator.tsx
│ │ │ │ ├── shadcn-io
│ │ │ │ │ └── kanban
│ │ │ │ │ └── index.tsx
│ │ │ │ └── textarea.tsx
│ │ │ ├── extension.ts
│ │ │ ├── index.ts
│ │ │ ├── lib
│ │ │ │ └── utils.ts
│ │ │ ├── services
│ │ │ │ ├── config-service.ts
│ │ │ │ ├── error-handler.ts
│ │ │ │ ├── notification-preferences.ts
│ │ │ │ ├── polling-service.ts
│ │ │ │ ├── polling-strategies.ts
│ │ │ │ ├── sidebar-webview-manager.ts
│ │ │ │ ├── task-repository.ts
│ │ │ │ ├── terminal-manager.ts
│ │ │ │ └── webview-manager.ts
│ │ │ ├── test
│ │ │ │ └── extension.test.ts
│ │ │ ├── utils
│ │ │ │ ├── configManager.ts
│ │ │ │ ├── connectionManager.ts
│ │ │ │ ├── errorHandler.ts
│ │ │ │ ├── event-emitter.ts
│ │ │ │ ├── logger.ts
│ │ │ │ ├── mcpClient.ts
│ │ │ │ ├── notificationPreferences.ts
│ │ │ │ └── task-master-api
│ │ │ │ ├── cache
│ │ │ │ │ └── cache-manager.ts
│ │ │ │ ├── index.ts
│ │ │ │ ├── mcp-client.ts
│ │ │ │ ├── transformers
│ │ │ │ │ └── task-transformer.ts
│ │ │ │ └── types
│ │ │ │ └── index.ts
│ │ │ └── webview
│ │ │ ├── App.tsx
│ │ │ ├── components
│ │ │ │ ├── AppContent.tsx
│ │ │ │ ├── EmptyState.tsx
│ │ │ │ ├── ErrorBoundary.tsx
│ │ │ │ ├── PollingStatus.tsx
│ │ │ │ ├── PriorityBadge.tsx
│ │ │ │ ├── SidebarView.tsx
│ │ │ │ ├── TagDropdown.tsx
│ │ │ │ ├── TaskCard.tsx
│ │ │ │ ├── TaskEditModal.tsx
│ │ │ │ ├── TaskMasterKanban.tsx
│ │ │ │ ├── ToastContainer.tsx
│ │ │ │ └── ToastNotification.tsx
│ │ │ ├── constants
│ │ │ │ └── index.ts
│ │ │ ├── contexts
│ │ │ │ └── VSCodeContext.tsx
│ │ │ ├── hooks
│ │ │ │ ├── useTaskQueries.ts
│ │ │ │ ├── useVSCodeMessages.ts
│ │ │ │ └── useWebviewHeight.ts
│ │ │ ├── index.css
│ │ │ ├── index.tsx
│ │ │ ├── providers
│ │ │ │ └── QueryProvider.tsx
│ │ │ ├── reducers
│ │ │ │ └── appReducer.ts
│ │ │ ├── sidebar.tsx
│ │ │ ├── types
│ │ │ │ └── index.ts
│ │ │ └── utils
│ │ │ ├── logger.ts
│ │ │ └── toast.ts
│ │ └── tsconfig.json
│ └── mcp
│ ├── CHANGELOG.md
│ ├── package.json
│ ├── src
│ │ ├── index.ts
│ │ ├── shared
│ │ │ ├── types.ts
│ │ │ └── utils.ts
│ │ └── tools
│ │ ├── autopilot
│ │ │ ├── abort.tool.ts
│ │ │ ├── commit.tool.ts
│ │ │ ├── complete.tool.ts
│ │ │ ├── finalize.tool.ts
│ │ │ ├── index.ts
│ │ │ ├── next.tool.ts
│ │ │ ├── resume.tool.ts
│ │ │ ├── start.tool.ts
│ │ │ └── status.tool.ts
│ │ ├── README-ZOD-V3.md
│ │ └── tasks
│ │ ├── get-task.tool.ts
│ │ ├── get-tasks.tool.ts
│ │ └── index.ts
│ ├── tsconfig.json
│ └── vitest.config.ts
├── assets
│ ├── .windsurfrules
│ ├── AGENTS.md
│ ├── claude
│ │ └── TM_COMMANDS_GUIDE.md
│ ├── config.json
│ ├── env.example
│ ├── example_prd_rpg.txt
│ ├── example_prd.txt
│ ├── GEMINI.md
│ ├── gitignore
│ ├── kiro-hooks
│ │ ├── tm-code-change-task-tracker.kiro.hook
│ │ ├── tm-complexity-analyzer.kiro.hook
│ │ ├── tm-daily-standup-assistant.kiro.hook
│ │ ├── tm-git-commit-task-linker.kiro.hook
│ │ ├── tm-pr-readiness-checker.kiro.hook
│ │ ├── tm-task-dependency-auto-progression.kiro.hook
│ │ └── tm-test-success-task-completer.kiro.hook
│ ├── roocode
│ │ ├── .roo
│ │ │ ├── rules-architect
│ │ │ │ └── architect-rules
│ │ │ ├── rules-ask
│ │ │ │ └── ask-rules
│ │ │ ├── rules-code
│ │ │ │ └── code-rules
│ │ │ ├── rules-debug
│ │ │ │ └── debug-rules
│ │ │ ├── rules-orchestrator
│ │ │ │ └── orchestrator-rules
│ │ │ └── rules-test
│ │ │ └── test-rules
│ │ └── .roomodes
│ ├── rules
│ │ ├── cursor_rules.mdc
│ │ ├── dev_workflow.mdc
│ │ ├── self_improve.mdc
│ │ ├── taskmaster_hooks_workflow.mdc
│ │ └── taskmaster.mdc
│ └── scripts_README.md
├── bin
│ └── task-master.js
├── biome.json
├── CHANGELOG.md
├── CLAUDE_CODE_PLUGIN.md
├── CLAUDE.md
├── context
│ ├── chats
│ │ ├── add-task-dependencies-1.md
│ │ └── max-min-tokens.txt.md
│ ├── fastmcp-core.txt
│ ├── fastmcp-docs.txt
│ ├── MCP_INTEGRATION.md
│ ├── mcp-js-sdk-docs.txt
│ ├── mcp-protocol-repo.txt
│ ├── mcp-protocol-schema-03262025.json
│ └── mcp-protocol-spec.txt
├── CONTRIBUTING.md
├── docs
│ ├── claude-code-integration.md
│ ├── CLI-COMMANDER-PATTERN.md
│ ├── command-reference.md
│ ├── configuration.md
│ ├── contributor-docs
│ │ ├── testing-roo-integration.md
│ │ └── worktree-setup.md
│ ├── cross-tag-task-movement.md
│ ├── examples
│ │ ├── claude-code-usage.md
│ │ └── codex-cli-usage.md
│ ├── examples.md
│ ├── licensing.md
│ ├── mcp-provider-guide.md
│ ├── mcp-provider.md
│ ├── migration-guide.md
│ ├── models.md
│ ├── providers
│ │ ├── codex-cli.md
│ │ └── gemini-cli.md
│ ├── README.md
│ ├── scripts
│ │ └── models-json-to-markdown.js
│ ├── task-structure.md
│ └── tutorial.md
├── images
│ ├── hamster-hiring.png
│ └── logo.png
├── index.js
├── jest.config.js
├── jest.resolver.cjs
├── LICENSE
├── llms-install.md
├── mcp-server
│ ├── server.js
│ └── src
│ ├── core
│ │ ├── __tests__
│ │ │ └── context-manager.test.js
│ │ ├── context-manager.js
│ │ ├── direct-functions
│ │ │ ├── add-dependency.js
│ │ │ ├── add-subtask.js
│ │ │ ├── add-tag.js
│ │ │ ├── add-task.js
│ │ │ ├── analyze-task-complexity.js
│ │ │ ├── cache-stats.js
│ │ │ ├── clear-subtasks.js
│ │ │ ├── complexity-report.js
│ │ │ ├── copy-tag.js
│ │ │ ├── create-tag-from-branch.js
│ │ │ ├── delete-tag.js
│ │ │ ├── expand-all-tasks.js
│ │ │ ├── expand-task.js
│ │ │ ├── fix-dependencies.js
│ │ │ ├── generate-task-files.js
│ │ │ ├── initialize-project.js
│ │ │ ├── list-tags.js
│ │ │ ├── models.js
│ │ │ ├── move-task-cross-tag.js
│ │ │ ├── move-task.js
│ │ │ ├── next-task.js
│ │ │ ├── parse-prd.js
│ │ │ ├── remove-dependency.js
│ │ │ ├── remove-subtask.js
│ │ │ ├── remove-task.js
│ │ │ ├── rename-tag.js
│ │ │ ├── research.js
│ │ │ ├── response-language.js
│ │ │ ├── rules.js
│ │ │ ├── scope-down.js
│ │ │ ├── scope-up.js
│ │ │ ├── set-task-status.js
│ │ │ ├── update-subtask-by-id.js
│ │ │ ├── update-task-by-id.js
│ │ │ ├── update-tasks.js
│ │ │ ├── use-tag.js
│ │ │ └── validate-dependencies.js
│ │ ├── task-master-core.js
│ │ └── utils
│ │ ├── env-utils.js
│ │ └── path-utils.js
│ ├── custom-sdk
│ │ ├── errors.js
│ │ ├── index.js
│ │ ├── json-extractor.js
│ │ ├── language-model.js
│ │ ├── message-converter.js
│ │ └── schema-converter.js
│ ├── index.js
│ ├── logger.js
│ ├── providers
│ │ └── mcp-provider.js
│ └── tools
│ ├── add-dependency.js
│ ├── add-subtask.js
│ ├── add-tag.js
│ ├── add-task.js
│ ├── analyze.js
│ ├── clear-subtasks.js
│ ├── complexity-report.js
│ ├── copy-tag.js
│ ├── delete-tag.js
│ ├── expand-all.js
│ ├── expand-task.js
│ ├── fix-dependencies.js
│ ├── generate.js
│ ├── get-operation-status.js
│ ├── index.js
│ ├── initialize-project.js
│ ├── list-tags.js
│ ├── models.js
│ ├── move-task.js
│ ├── next-task.js
│ ├── parse-prd.js
│ ├── README-ZOD-V3.md
│ ├── remove-dependency.js
│ ├── remove-subtask.js
│ ├── remove-task.js
│ ├── rename-tag.js
│ ├── research.js
│ ├── response-language.js
│ ├── rules.js
│ ├── scope-down.js
│ ├── scope-up.js
│ ├── set-task-status.js
│ ├── tool-registry.js
│ ├── update-subtask.js
│ ├── update-task.js
│ ├── update.js
│ ├── use-tag.js
│ ├── utils.js
│ └── validate-dependencies.js
├── mcp-test.js
├── output.json
├── package-lock.json
├── package.json
├── packages
│ ├── ai-sdk-provider-grok-cli
│ │ ├── CHANGELOG.md
│ │ ├── package.json
│ │ ├── README.md
│ │ ├── src
│ │ │ ├── errors.test.ts
│ │ │ ├── errors.ts
│ │ │ ├── grok-cli-language-model.ts
│ │ │ ├── grok-cli-provider.test.ts
│ │ │ ├── grok-cli-provider.ts
│ │ │ ├── index.ts
│ │ │ ├── json-extractor.test.ts
│ │ │ ├── json-extractor.ts
│ │ │ ├── message-converter.test.ts
│ │ │ ├── message-converter.ts
│ │ │ └── types.ts
│ │ └── tsconfig.json
│ ├── build-config
│ │ ├── CHANGELOG.md
│ │ ├── package.json
│ │ ├── src
│ │ │ └── tsdown.base.ts
│ │ └── tsconfig.json
│ ├── claude-code-plugin
│ │ ├── .claude-plugin
│ │ │ └── plugin.json
│ │ ├── .gitignore
│ │ ├── agents
│ │ │ ├── task-checker.md
│ │ │ ├── task-executor.md
│ │ │ └── task-orchestrator.md
│ │ ├── CHANGELOG.md
│ │ ├── commands
│ │ │ ├── add-dependency.md
│ │ │ ├── add-subtask.md
│ │ │ ├── add-task.md
│ │ │ ├── analyze-complexity.md
│ │ │ ├── analyze-project.md
│ │ │ ├── auto-implement-tasks.md
│ │ │ ├── command-pipeline.md
│ │ │ ├── complexity-report.md
│ │ │ ├── convert-task-to-subtask.md
│ │ │ ├── expand-all-tasks.md
│ │ │ ├── expand-task.md
│ │ │ ├── fix-dependencies.md
│ │ │ ├── generate-tasks.md
│ │ │ ├── help.md
│ │ │ ├── init-project-quick.md
│ │ │ ├── init-project.md
│ │ │ ├── install-taskmaster.md
│ │ │ ├── learn.md
│ │ │ ├── list-tasks-by-status.md
│ │ │ ├── list-tasks-with-subtasks.md
│ │ │ ├── list-tasks.md
│ │ │ ├── next-task.md
│ │ │ ├── parse-prd-with-research.md
│ │ │ ├── parse-prd.md
│ │ │ ├── project-status.md
│ │ │ ├── quick-install-taskmaster.md
│ │ │ ├── remove-all-subtasks.md
│ │ │ ├── remove-dependency.md
│ │ │ ├── remove-subtask.md
│ │ │ ├── remove-subtasks.md
│ │ │ ├── remove-task.md
│ │ │ ├── setup-models.md
│ │ │ ├── show-task.md
│ │ │ ├── smart-workflow.md
│ │ │ ├── sync-readme.md
│ │ │ ├── tm-main.md
│ │ │ ├── to-cancelled.md
│ │ │ ├── to-deferred.md
│ │ │ ├── to-done.md
│ │ │ ├── to-in-progress.md
│ │ │ ├── to-pending.md
│ │ │ ├── to-review.md
│ │ │ ├── update-single-task.md
│ │ │ ├── update-task.md
│ │ │ ├── update-tasks-from-id.md
│ │ │ ├── validate-dependencies.md
│ │ │ └── view-models.md
│ │ ├── mcp.json
│ │ └── package.json
│ ├── tm-bridge
│ │ ├── CHANGELOG.md
│ │ ├── package.json
│ │ ├── README.md
│ │ ├── src
│ │ │ ├── add-tag-bridge.ts
│ │ │ ├── bridge-types.ts
│ │ │ ├── bridge-utils.ts
│ │ │ ├── expand-bridge.ts
│ │ │ ├── index.ts
│ │ │ ├── tags-bridge.ts
│ │ │ ├── update-bridge.ts
│ │ │ └── use-tag-bridge.ts
│ │ └── tsconfig.json
│ └── tm-core
│ ├── .gitignore
│ ├── CHANGELOG.md
│ ├── docs
│ │ └── listTasks-architecture.md
│ ├── package.json
│ ├── POC-STATUS.md
│ ├── README.md
│ ├── src
│ │ ├── common
│ │ │ ├── constants
│ │ │ │ ├── index.ts
│ │ │ │ ├── paths.ts
│ │ │ │ └── providers.ts
│ │ │ ├── errors
│ │ │ │ ├── index.ts
│ │ │ │ └── task-master-error.ts
│ │ │ ├── interfaces
│ │ │ │ ├── configuration.interface.ts
│ │ │ │ ├── index.ts
│ │ │ │ └── storage.interface.ts
│ │ │ ├── logger
│ │ │ │ ├── factory.ts
│ │ │ │ ├── index.ts
│ │ │ │ ├── logger.spec.ts
│ │ │ │ └── logger.ts
│ │ │ ├── mappers
│ │ │ │ ├── TaskMapper.test.ts
│ │ │ │ └── TaskMapper.ts
│ │ │ ├── types
│ │ │ │ ├── database.types.ts
│ │ │ │ ├── index.ts
│ │ │ │ ├── legacy.ts
│ │ │ │ └── repository-types.ts
│ │ │ └── utils
│ │ │ ├── git-utils.ts
│ │ │ ├── id-generator.ts
│ │ │ ├── index.ts
│ │ │ ├── path-helpers.ts
│ │ │ ├── path-normalizer.spec.ts
│ │ │ ├── path-normalizer.ts
│ │ │ ├── project-root-finder.spec.ts
│ │ │ ├── project-root-finder.ts
│ │ │ ├── run-id-generator.spec.ts
│ │ │ └── run-id-generator.ts
│ │ ├── index.ts
│ │ ├── modules
│ │ │ ├── ai
│ │ │ │ ├── index.ts
│ │ │ │ ├── interfaces
│ │ │ │ │ └── ai-provider.interface.ts
│ │ │ │ └── providers
│ │ │ │ ├── base-provider.ts
│ │ │ │ └── index.ts
│ │ │ ├── auth
│ │ │ │ ├── auth-domain.spec.ts
│ │ │ │ ├── auth-domain.ts
│ │ │ │ ├── config.ts
│ │ │ │ ├── index.ts
│ │ │ │ ├── managers
│ │ │ │ │ ├── auth-manager.spec.ts
│ │ │ │ │ └── auth-manager.ts
│ │ │ │ ├── services
│ │ │ │ │ ├── context-store.ts
│ │ │ │ │ ├── oauth-service.ts
│ │ │ │ │ ├── organization.service.ts
│ │ │ │ │ ├── supabase-session-storage.spec.ts
│ │ │ │ │ └── supabase-session-storage.ts
│ │ │ │ └── types.ts
│ │ │ ├── briefs
│ │ │ │ ├── briefs-domain.ts
│ │ │ │ ├── index.ts
│ │ │ │ ├── services
│ │ │ │ │ └── brief-service.ts
│ │ │ │ ├── types.ts
│ │ │ │ └── utils
│ │ │ │ └── url-parser.ts
│ │ │ ├── commands
│ │ │ │ └── index.ts
│ │ │ ├── config
│ │ │ │ ├── config-domain.ts
│ │ │ │ ├── index.ts
│ │ │ │ ├── managers
│ │ │ │ │ ├── config-manager.spec.ts
│ │ │ │ │ └── config-manager.ts
│ │ │ │ └── services
│ │ │ │ ├── config-loader.service.spec.ts
│ │ │ │ ├── config-loader.service.ts
│ │ │ │ ├── config-merger.service.spec.ts
│ │ │ │ ├── config-merger.service.ts
│ │ │ │ ├── config-persistence.service.spec.ts
│ │ │ │ ├── config-persistence.service.ts
│ │ │ │ ├── environment-config-provider.service.spec.ts
│ │ │ │ ├── environment-config-provider.service.ts
│ │ │ │ ├── index.ts
│ │ │ │ ├── runtime-state-manager.service.spec.ts
│ │ │ │ └── runtime-state-manager.service.ts
│ │ │ ├── dependencies
│ │ │ │ └── index.ts
│ │ │ ├── execution
│ │ │ │ ├── executors
│ │ │ │ │ ├── base-executor.ts
│ │ │ │ │ ├── claude-executor.ts
│ │ │ │ │ └── executor-factory.ts
│ │ │ │ ├── index.ts
│ │ │ │ ├── services
│ │ │ │ │ └── executor-service.ts
│ │ │ │ └── types.ts
│ │ │ ├── git
│ │ │ │ ├── adapters
│ │ │ │ │ ├── git-adapter.test.ts
│ │ │ │ │ └── git-adapter.ts
│ │ │ │ ├── git-domain.ts
│ │ │ │ ├── index.ts
│ │ │ │ └── services
│ │ │ │ ├── branch-name-generator.spec.ts
│ │ │ │ ├── branch-name-generator.ts
│ │ │ │ ├── commit-message-generator.test.ts
│ │ │ │ ├── commit-message-generator.ts
│ │ │ │ ├── scope-detector.test.ts
│ │ │ │ ├── scope-detector.ts
│ │ │ │ ├── template-engine.test.ts
│ │ │ │ └── template-engine.ts
│ │ │ ├── integration
│ │ │ │ ├── clients
│ │ │ │ │ ├── index.ts
│ │ │ │ │ └── supabase-client.ts
│ │ │ │ ├── integration-domain.ts
│ │ │ │ └── services
│ │ │ │ ├── export.service.ts
│ │ │ │ ├── task-expansion.service.ts
│ │ │ │ └── task-retrieval.service.ts
│ │ │ ├── reports
│ │ │ │ ├── index.ts
│ │ │ │ ├── managers
│ │ │ │ │ └── complexity-report-manager.ts
│ │ │ │ └── types.ts
│ │ │ ├── storage
│ │ │ │ ├── adapters
│ │ │ │ │ ├── activity-logger.ts
│ │ │ │ │ ├── api-storage.ts
│ │ │ │ │ └── file-storage
│ │ │ │ │ ├── file-operations.ts
│ │ │ │ │ ├── file-storage.ts
│ │ │ │ │ ├── format-handler.ts
│ │ │ │ │ ├── index.ts
│ │ │ │ │ └── path-resolver.ts
│ │ │ │ ├── index.ts
│ │ │ │ ├── services
│ │ │ │ │ └── storage-factory.ts
│ │ │ │ └── utils
│ │ │ │ └── api-client.ts
│ │ │ ├── tasks
│ │ │ │ ├── entities
│ │ │ │ │ └── task.entity.ts
│ │ │ │ ├── parser
│ │ │ │ │ └── index.ts
│ │ │ │ ├── repositories
│ │ │ │ │ ├── supabase
│ │ │ │ │ │ ├── dependency-fetcher.ts
│ │ │ │ │ │ ├── index.ts
│ │ │ │ │ │ └── supabase-repository.ts
│ │ │ │ │ └── task-repository.interface.ts
│ │ │ │ ├── services
│ │ │ │ │ ├── preflight-checker.service.ts
│ │ │ │ │ ├── tag.service.ts
│ │ │ │ │ ├── task-execution-service.ts
│ │ │ │ │ ├── task-loader.service.ts
│ │ │ │ │ └── task-service.ts
│ │ │ │ └── tasks-domain.ts
│ │ │ ├── ui
│ │ │ │ └── index.ts
│ │ │ └── workflow
│ │ │ ├── managers
│ │ │ │ ├── workflow-state-manager.spec.ts
│ │ │ │ └── workflow-state-manager.ts
│ │ │ ├── orchestrators
│ │ │ │ ├── workflow-orchestrator.test.ts
│ │ │ │ └── workflow-orchestrator.ts
│ │ │ ├── services
│ │ │ │ ├── test-result-validator.test.ts
│ │ │ │ ├── test-result-validator.ts
│ │ │ │ ├── test-result-validator.types.ts
│ │ │ │ ├── workflow-activity-logger.ts
│ │ │ │ └── workflow.service.ts
│ │ │ ├── types.ts
│ │ │ └── workflow-domain.ts
│ │ ├── subpath-exports.test.ts
│ │ ├── tm-core.ts
│ │ └── utils
│ │ └── time.utils.ts
│ ├── tests
│ │ ├── auth
│ │ │ └── auth-refresh.test.ts
│ │ ├── integration
│ │ │ ├── auth-token-refresh.test.ts
│ │ │ ├── list-tasks.test.ts
│ │ │ └── storage
│ │ │ └── activity-logger.test.ts
│ │ ├── mocks
│ │ │ └── mock-provider.ts
│ │ ├── setup.ts
│ │ └── unit
│ │ ├── base-provider.test.ts
│ │ ├── executor.test.ts
│ │ └── smoke.test.ts
│ ├── tsconfig.json
│ └── vitest.config.ts
├── README-task-master.md
├── README.md
├── scripts
│ ├── create-worktree.sh
│ ├── dev.js
│ ├── init.js
│ ├── list-worktrees.sh
│ ├── modules
│ │ ├── ai-services-unified.js
│ │ ├── bridge-utils.js
│ │ ├── commands.js
│ │ ├── config-manager.js
│ │ ├── dependency-manager.js
│ │ ├── index.js
│ │ ├── prompt-manager.js
│ │ ├── supported-models.json
│ │ ├── sync-readme.js
│ │ ├── task-manager
│ │ │ ├── add-subtask.js
│ │ │ ├── add-task.js
│ │ │ ├── analyze-task-complexity.js
│ │ │ ├── clear-subtasks.js
│ │ │ ├── expand-all-tasks.js
│ │ │ ├── expand-task.js
│ │ │ ├── find-next-task.js
│ │ │ ├── generate-task-files.js
│ │ │ ├── is-task-dependent.js
│ │ │ ├── list-tasks.js
│ │ │ ├── migrate.js
│ │ │ ├── models.js
│ │ │ ├── move-task.js
│ │ │ ├── parse-prd
│ │ │ │ ├── index.js
│ │ │ │ ├── parse-prd-config.js
│ │ │ │ ├── parse-prd-helpers.js
│ │ │ │ ├── parse-prd-non-streaming.js
│ │ │ │ ├── parse-prd-streaming.js
│ │ │ │ └── parse-prd.js
│ │ │ ├── remove-subtask.js
│ │ │ ├── remove-task.js
│ │ │ ├── research.js
│ │ │ ├── response-language.js
│ │ │ ├── scope-adjustment.js
│ │ │ ├── set-task-status.js
│ │ │ ├── tag-management.js
│ │ │ ├── task-exists.js
│ │ │ ├── update-single-task-status.js
│ │ │ ├── update-subtask-by-id.js
│ │ │ ├── update-task-by-id.js
│ │ │ └── update-tasks.js
│ │ ├── task-manager.js
│ │ ├── ui.js
│ │ ├── update-config-tokens.js
│ │ ├── utils
│ │ │ ├── contextGatherer.js
│ │ │ ├── fuzzyTaskSearch.js
│ │ │ └── git-utils.js
│ │ └── utils.js
│ ├── task-complexity-report.json
│ ├── test-claude-errors.js
│ └── test-claude.js
├── sonar-project.properties
├── src
│ ├── ai-providers
│ │ ├── anthropic.js
│ │ ├── azure.js
│ │ ├── base-provider.js
│ │ ├── bedrock.js
│ │ ├── claude-code.js
│ │ ├── codex-cli.js
│ │ ├── gemini-cli.js
│ │ ├── google-vertex.js
│ │ ├── google.js
│ │ ├── grok-cli.js
│ │ ├── groq.js
│ │ ├── index.js
│ │ ├── lmstudio.js
│ │ ├── ollama.js
│ │ ├── openai-compatible.js
│ │ ├── openai.js
│ │ ├── openrouter.js
│ │ ├── perplexity.js
│ │ ├── xai.js
│ │ ├── zai-coding.js
│ │ └── zai.js
│ ├── constants
│ │ ├── commands.js
│ │ ├── paths.js
│ │ ├── profiles.js
│ │ ├── rules-actions.js
│ │ ├── task-priority.js
│ │ └── task-status.js
│ ├── profiles
│ │ ├── amp.js
│ │ ├── base-profile.js
│ │ ├── claude.js
│ │ ├── cline.js
│ │ ├── codex.js
│ │ ├── cursor.js
│ │ ├── gemini.js
│ │ ├── index.js
│ │ ├── kilo.js
│ │ ├── kiro.js
│ │ ├── opencode.js
│ │ ├── roo.js
│ │ ├── trae.js
│ │ ├── vscode.js
│ │ ├── windsurf.js
│ │ └── zed.js
│ ├── progress
│ │ ├── base-progress-tracker.js
│ │ ├── cli-progress-factory.js
│ │ ├── parse-prd-tracker.js
│ │ ├── progress-tracker-builder.js
│ │ └── tracker-ui.js
│ ├── prompts
│ │ ├── add-task.json
│ │ ├── analyze-complexity.json
│ │ ├── expand-task.json
│ │ ├── parse-prd.json
│ │ ├── README.md
│ │ ├── research.json
│ │ ├── schemas
│ │ │ ├── parameter.schema.json
│ │ │ ├── prompt-template.schema.json
│ │ │ ├── README.md
│ │ │ └── variant.schema.json
│ │ ├── update-subtask.json
│ │ ├── update-task.json
│ │ └── update-tasks.json
│ ├── provider-registry
│ │ └── index.js
│ ├── schemas
│ │ ├── add-task.js
│ │ ├── analyze-complexity.js
│ │ ├── base-schemas.js
│ │ ├── expand-task.js
│ │ ├── parse-prd.js
│ │ ├── registry.js
│ │ ├── update-subtask.js
│ │ ├── update-task.js
│ │ └── update-tasks.js
│ ├── task-master.js
│ ├── ui
│ │ ├── confirm.js
│ │ ├── indicators.js
│ │ └── parse-prd.js
│ └── utils
│ ├── asset-resolver.js
│ ├── create-mcp-config.js
│ ├── format.js
│ ├── getVersion.js
│ ├── logger-utils.js
│ ├── manage-gitignore.js
│ ├── path-utils.js
│ ├── profiles.js
│ ├── rule-transformer.js
│ ├── stream-parser.js
│ └── timeout-manager.js
├── test-clean-tags.js
├── test-config-manager.js
├── test-prd.txt
├── test-tag-functions.js
├── test-version-check-full.js
├── test-version-check.js
├── tests
│ ├── e2e
│ │ ├── e2e_helpers.sh
│ │ ├── parse_llm_output.cjs
│ │ ├── run_e2e.sh
│ │ ├── run_fallback_verification.sh
│ │ └── test_llm_analysis.sh
│ ├── fixtures
│ │ ├── .taskmasterconfig
│ │ ├── sample-claude-response.js
│ │ ├── sample-prd.txt
│ │ └── sample-tasks.js
│ ├── helpers
│ │ └── tool-counts.js
│ ├── integration
│ │ ├── claude-code-error-handling.test.js
│ │ ├── claude-code-optional.test.js
│ │ ├── cli
│ │ │ ├── commands.test.js
│ │ │ ├── complex-cross-tag-scenarios.test.js
│ │ │ └── move-cross-tag.test.js
│ │ ├── manage-gitignore.test.js
│ │ ├── mcp-server
│ │ │ └── direct-functions.test.js
│ │ ├── move-task-cross-tag.integration.test.js
│ │ ├── move-task-simple.integration.test.js
│ │ ├── profiles
│ │ │ ├── amp-init-functionality.test.js
│ │ │ ├── claude-init-functionality.test.js
│ │ │ ├── cline-init-functionality.test.js
│ │ │ ├── codex-init-functionality.test.js
│ │ │ ├── cursor-init-functionality.test.js
│ │ │ ├── gemini-init-functionality.test.js
│ │ │ ├── opencode-init-functionality.test.js
│ │ │ ├── roo-files-inclusion.test.js
│ │ │ ├── roo-init-functionality.test.js
│ │ │ ├── rules-files-inclusion.test.js
│ │ │ ├── trae-init-functionality.test.js
│ │ │ ├── vscode-init-functionality.test.js
│ │ │ └── windsurf-init-functionality.test.js
│ │ └── providers
│ │ └── temperature-support.test.js
│ ├── manual
│ │ ├── progress
│ │ │ ├── parse-prd-analysis.js
│ │ │ ├── test-parse-prd.js
│ │ │ └── TESTING_GUIDE.md
│ │ └── prompts
│ │ ├── prompt-test.js
│ │ └── README.md
│ ├── README.md
│ ├── setup.js
│ └── unit
│ ├── ai-providers
│ │ ├── base-provider.test.js
│ │ ├── claude-code.test.js
│ │ ├── codex-cli.test.js
│ │ ├── gemini-cli.test.js
│ │ ├── lmstudio.test.js
│ │ ├── mcp-components.test.js
│ │ ├── openai-compatible.test.js
│ │ ├── openai.test.js
│ │ ├── provider-registry.test.js
│ │ ├── zai-coding.test.js
│ │ ├── zai-provider.test.js
│ │ ├── zai-schema-introspection.test.js
│ │ └── zai.test.js
│ ├── ai-services-unified.test.js
│ ├── commands.test.js
│ ├── config-manager.test.js
│ ├── config-manager.test.mjs
│ ├── dependency-manager.test.js
│ ├── init.test.js
│ ├── initialize-project.test.js
│ ├── kebab-case-validation.test.js
│ ├── manage-gitignore.test.js
│ ├── mcp
│ │ └── tools
│ │ ├── __mocks__
│ │ │ └── move-task.js
│ │ ├── add-task.test.js
│ │ ├── analyze-complexity.test.js
│ │ ├── expand-all.test.js
│ │ ├── get-tasks.test.js
│ │ ├── initialize-project.test.js
│ │ ├── move-task-cross-tag-options.test.js
│ │ ├── move-task-cross-tag.test.js
│ │ ├── remove-task.test.js
│ │ └── tool-registration.test.js
│ ├── mcp-providers
│ │ ├── mcp-components.test.js
│ │ └── mcp-provider.test.js
│ ├── parse-prd.test.js
│ ├── profiles
│ │ ├── amp-integration.test.js
│ │ ├── claude-integration.test.js
│ │ ├── cline-integration.test.js
│ │ ├── codex-integration.test.js
│ │ ├── cursor-integration.test.js
│ │ ├── gemini-integration.test.js
│ │ ├── kilo-integration.test.js
│ │ ├── kiro-integration.test.js
│ │ ├── mcp-config-validation.test.js
│ │ ├── opencode-integration.test.js
│ │ ├── profile-safety-check.test.js
│ │ ├── roo-integration.test.js
│ │ ├── rule-transformer-cline.test.js
│ │ ├── rule-transformer-cursor.test.js
│ │ ├── rule-transformer-gemini.test.js
│ │ ├── rule-transformer-kilo.test.js
│ │ ├── rule-transformer-kiro.test.js
│ │ ├── rule-transformer-opencode.test.js
│ │ ├── rule-transformer-roo.test.js
│ │ ├── rule-transformer-trae.test.js
│ │ ├── rule-transformer-vscode.test.js
│ │ ├── rule-transformer-windsurf.test.js
│ │ ├── rule-transformer-zed.test.js
│ │ ├── rule-transformer.test.js
│ │ ├── selective-profile-removal.test.js
│ │ ├── subdirectory-support.test.js
│ │ ├── trae-integration.test.js
│ │ ├── vscode-integration.test.js
│ │ ├── windsurf-integration.test.js
│ │ └── zed-integration.test.js
│ ├── progress
│ │ └── base-progress-tracker.test.js
│ ├── prompt-manager.test.js
│ ├── prompts
│ │ ├── expand-task-prompt.test.js
│ │ └── prompt-migration.test.js
│ ├── scripts
│ │ └── modules
│ │ ├── commands
│ │ │ ├── move-cross-tag.test.js
│ │ │ └── README.md
│ │ ├── dependency-manager
│ │ │ ├── circular-dependencies.test.js
│ │ │ ├── cross-tag-dependencies.test.js
│ │ │ └── fix-dependencies-command.test.js
│ │ ├── task-manager
│ │ │ ├── add-subtask.test.js
│ │ │ ├── add-task.test.js
│ │ │ ├── analyze-task-complexity.test.js
│ │ │ ├── clear-subtasks.test.js
│ │ │ ├── complexity-report-tag-isolation.test.js
│ │ │ ├── expand-all-tasks.test.js
│ │ │ ├── expand-task.test.js
│ │ │ ├── find-next-task.test.js
│ │ │ ├── generate-task-files.test.js
│ │ │ ├── list-tasks.test.js
│ │ │ ├── models-baseurl.test.js
│ │ │ ├── move-task-cross-tag.test.js
│ │ │ ├── move-task.test.js
│ │ │ ├── parse-prd-schema.test.js
│ │ │ ├── parse-prd.test.js
│ │ │ ├── remove-subtask.test.js
│ │ │ ├── remove-task.test.js
│ │ │ ├── research.test.js
│ │ │ ├── scope-adjustment.test.js
│ │ │ ├── set-task-status.test.js
│ │ │ ├── setup.js
│ │ │ ├── update-single-task-status.test.js
│ │ │ ├── update-subtask-by-id.test.js
│ │ │ ├── update-task-by-id.test.js
│ │ │ └── update-tasks.test.js
│ │ ├── ui
│ │ │ └── cross-tag-error-display.test.js
│ │ └── utils-tag-aware-paths.test.js
│ ├── task-finder.test.js
│ ├── task-manager
│ │ ├── clear-subtasks.test.js
│ │ ├── move-task.test.js
│ │ ├── tag-boundary.test.js
│ │ └── tag-management.test.js
│ ├── task-master.test.js
│ ├── ui
│ │ └── indicators.test.js
│ ├── ui.test.js
│ ├── utils-strip-ansi.test.js
│ └── utils.test.js
├── tsconfig.json
├── tsdown.config.ts
├── turbo.json
└── update-task-migration-plan.md
```
# Files
--------------------------------------------------------------------------------
/tests/integration/move-task-simple.integration.test.js:
--------------------------------------------------------------------------------
```javascript
import { jest } from '@jest/globals';
import path from 'path';
import mockFs from 'mock-fs';
import fs from 'fs';
import { fileURLToPath } from 'url';
// Import the actual move task functionality
import moveTask, {
moveTasksBetweenTags
} from '../../scripts/modules/task-manager/move-task.js';
import { readJSON, writeJSON } from '../../scripts/modules/utils.js';
// Mock console to avoid conflicts with mock-fs
const originalConsole = { ...console };
beforeAll(() => {
global.console = {
...console,
log: jest.fn(),
error: jest.fn(),
warn: jest.fn(),
info: jest.fn()
};
});
afterAll(() => {
global.console = originalConsole;
});
// Get __dirname equivalent for ES modules
const __filename = fileURLToPath(import.meta.url);
const __dirname = path.dirname(__filename);
describe('Cross-Tag Task Movement Simple Integration Tests', () => {
const testDataDir = path.join(__dirname, 'fixtures');
const testTasksPath = path.join(testDataDir, 'tasks.json');
// Test data structure with proper tagged format
const testData = {
backlog: {
tasks: [
{ id: 1, title: 'Task 1', dependencies: [], status: 'pending' },
{ id: 2, title: 'Task 2', dependencies: [], status: 'pending' }
]
},
'in-progress': {
tasks: [
{ id: 3, title: 'Task 3', dependencies: [], status: 'in-progress' }
]
}
};
beforeEach(() => {
// Set up mock file system with test data
mockFs({
[testDataDir]: {
'tasks.json': JSON.stringify(testData, null, 2)
}
});
});
afterEach(() => {
// Clean up mock file system
mockFs.restore();
});
describe('Real Module Integration Tests', () => {
it('should move task within same tag using actual moveTask function', async () => {
// Test moving Task 1 from position 1 to position 5 within backlog tag
const result = await moveTask(
testTasksPath,
'1',
'5',
false, // Don't generate files for this test
{ tag: 'backlog' }
);
// Verify the move operation was successful
expect(result).toBeDefined();
expect(result.message).toContain('Moved task 1 to new ID 5');
// Read the updated data to verify the move actually happened
const updatedData = readJSON(testTasksPath, null, 'backlog');
const rawData = updatedData._rawTaggedData || updatedData;
const backlogTasks = rawData.backlog.tasks;
// Verify Task 1 is no longer at position 1
const taskAtPosition1 = backlogTasks.find((t) => t.id === 1);
expect(taskAtPosition1).toBeUndefined();
// Verify Task 1 is now at position 5
const taskAtPosition5 = backlogTasks.find((t) => t.id === 5);
expect(taskAtPosition5).toBeDefined();
expect(taskAtPosition5.title).toBe('Task 1');
expect(taskAtPosition5.status).toBe('pending');
});
it('should move tasks between tags using moveTasksBetweenTags function', async () => {
// Test moving Task 1 from backlog to in-progress tag
const result = await moveTasksBetweenTags(
testTasksPath,
['1'], // Task IDs to move (as strings)
'backlog', // Source tag
'in-progress', // Target tag
{ withDependencies: false, ignoreDependencies: false },
{ projectRoot: testDataDir }
);
// Verify the cross-tag move operation was successful
expect(result).toBeDefined();
expect(result.message).toContain(
'Successfully moved 1 tasks from "backlog" to "in-progress"'
);
expect(result.movedTasks).toHaveLength(1);
expect(result.movedTasks[0].id).toBe('1');
expect(result.movedTasks[0].fromTag).toBe('backlog');
expect(result.movedTasks[0].toTag).toBe('in-progress');
// Read the updated data to verify the move actually happened
const updatedData = readJSON(testTasksPath, null, 'backlog');
// readJSON returns resolved data, so we need to access the raw tagged data
const rawData = updatedData._rawTaggedData || updatedData;
const backlogTasks = rawData.backlog?.tasks || [];
const inProgressTasks = rawData['in-progress']?.tasks || [];
// Verify Task 1 is no longer in backlog
const taskInBacklog = backlogTasks.find((t) => t.id === 1);
expect(taskInBacklog).toBeUndefined();
// Verify Task 1 is now in in-progress
const taskInProgress = inProgressTasks.find((t) => t.id === 1);
expect(taskInProgress).toBeDefined();
expect(taskInProgress.title).toBe('Task 1');
expect(taskInProgress.status).toBe('pending');
});
it('should handle subtask movement restrictions', async () => {
// Create data with subtasks
const dataWithSubtasks = {
backlog: {
tasks: [
{
id: 1,
title: 'Task 1',
dependencies: [],
status: 'pending',
subtasks: [
{ id: '1.1', title: 'Subtask 1.1', status: 'pending' },
{ id: '1.2', title: 'Subtask 1.2', status: 'pending' }
]
}
]
},
'in-progress': {
tasks: [
{ id: 2, title: 'Task 2', dependencies: [], status: 'in-progress' }
]
}
};
// Write subtask data to mock file system
mockFs({
[testDataDir]: {
'tasks.json': JSON.stringify(dataWithSubtasks, null, 2)
}
});
// Try to move a subtask directly - this should actually work (converts subtask to task)
const result = await moveTask(
testTasksPath,
'1.1', // Subtask ID
'5', // New task ID
false,
{ tag: 'backlog' }
);
// Verify the subtask was converted to a task
expect(result).toBeDefined();
expect(result.message).toContain('Converted subtask 1.1 to task 5');
// Verify the subtask was removed from the parent and converted to a standalone task
const updatedData = readJSON(testTasksPath, null, 'backlog');
const rawData = updatedData._rawTaggedData || updatedData;
const task1 = rawData.backlog?.tasks?.find((t) => t.id === 1);
const newTask5 = rawData.backlog?.tasks?.find((t) => t.id === 5);
expect(task1).toBeDefined();
expect(task1.subtasks).toHaveLength(1); // Only 1.2 remains
expect(task1.subtasks[0].id).toBe(2);
expect(newTask5).toBeDefined();
expect(newTask5.title).toBe('Subtask 1.1');
expect(newTask5.status).toBe('pending');
});
it('should handle missing source tag errors', async () => {
// Try to move from a non-existent tag
await expect(
moveTasksBetweenTags(
testTasksPath,
['1'],
'non-existent-tag', // Source tag doesn't exist
'in-progress',
{ withDependencies: false, ignoreDependencies: false },
{ projectRoot: testDataDir }
)
).rejects.toThrow();
});
it('should handle missing task ID errors', async () => {
// Try to move a non-existent task
await expect(
moveTask(
testTasksPath,
'999', // Non-existent task ID
'5',
false,
{ tag: 'backlog' }
)
).rejects.toThrow();
});
it('should handle ignoreDependencies option correctly', async () => {
// Create data with dependencies
const dataWithDependencies = {
backlog: {
tasks: [
{ id: 1, title: 'Task 1', dependencies: [2], status: 'pending' },
{ id: 2, title: 'Task 2', dependencies: [], status: 'pending' }
]
},
'in-progress': {
tasks: [
{ id: 3, title: 'Task 3', dependencies: [], status: 'in-progress' }
]
}
};
// Write dependency data to mock file system
mockFs({
[testDataDir]: {
'tasks.json': JSON.stringify(dataWithDependencies, null, 2)
}
});
// Move Task 1 while ignoring its dependencies
const result = await moveTasksBetweenTags(
testTasksPath,
['1'], // Only Task 1
'backlog',
'in-progress',
{ withDependencies: false, ignoreDependencies: true },
{ projectRoot: testDataDir }
);
expect(result).toBeDefined();
expect(result.movedTasks).toHaveLength(1);
// Verify Task 1 moved but Task 2 stayed
const updatedData = readJSON(testTasksPath, null, 'backlog');
const rawData = updatedData._rawTaggedData || updatedData;
expect(rawData.backlog.tasks).toHaveLength(1); // Task 2 remains
expect(rawData['in-progress'].tasks).toHaveLength(2); // Task 3 + Task 1
// Verify Task 1 has no dependencies (they were ignored)
const movedTask = rawData['in-progress'].tasks.find((t) => t.id === 1);
expect(movedTask.dependencies).toEqual([]);
});
});
describe('Complex Dependency Scenarios', () => {
beforeAll(() => {
// Document the mock-fs limitation for complex dependency scenarios
console.warn(
'⚠️ Complex dependency tests are skipped due to mock-fs limitations. ' +
'These tests require real filesystem operations for proper dependency resolution. ' +
'Consider using real temporary filesystem setup for these scenarios.'
);
});
it.skip('should handle dependency conflicts during cross-tag moves', async () => {
// For now, skip this test as the mock setup is not working correctly
// TODO: Fix mock-fs setup for complex dependency scenarios
});
it.skip('should handle withDependencies option correctly', async () => {
// For now, skip this test as the mock setup is not working correctly
// TODO: Fix mock-fs setup for complex dependency scenarios
});
});
describe('Complex Dependency Integration Tests with Mock-fs', () => {
const complexTestData = {
backlog: {
tasks: [
{ id: 1, title: 'Task 1', dependencies: [2, 3], status: 'pending' },
{ id: 2, title: 'Task 2', dependencies: [4], status: 'pending' },
{ id: 3, title: 'Task 3', dependencies: [], status: 'pending' },
{ id: 4, title: 'Task 4', dependencies: [], status: 'pending' }
]
},
'in-progress': {
tasks: [
{ id: 5, title: 'Task 5', dependencies: [], status: 'in-progress' }
]
}
};
beforeEach(() => {
// Set up mock file system with complex dependency data
mockFs({
[testDataDir]: {
'tasks.json': JSON.stringify(complexTestData, null, 2)
}
});
});
afterEach(() => {
// Clean up mock file system
mockFs.restore();
});
it('should handle dependency conflicts during cross-tag moves using actual move functions', async () => {
// Test moving Task 1 which has dependencies on Tasks 2 and 3
// This should fail because Task 1 depends on Tasks 2 and 3 which are in the same tag
await expect(
moveTasksBetweenTags(
testTasksPath,
['1'], // Task 1 with dependencies
'backlog',
'in-progress',
{ withDependencies: false, ignoreDependencies: false },
{ projectRoot: testDataDir }
)
).rejects.toThrow(
'Cannot move tasks: 2 cross-tag dependency conflicts found'
);
});
it('should handle withDependencies option correctly using actual move functions', async () => {
// Test moving Task 1 with its dependencies (Tasks 2 and 3)
// Task 2 also depends on Task 4, so all 4 tasks should move
const result = await moveTasksBetweenTags(
testTasksPath,
['1'], // Task 1
'backlog',
'in-progress',
{ withDependencies: true, ignoreDependencies: false },
{ projectRoot: testDataDir }
);
// Verify the move operation was successful
expect(result).toBeDefined();
expect(result.message).toContain(
'Successfully moved 4 tasks from "backlog" to "in-progress"'
);
expect(result.movedTasks).toHaveLength(4); // Task 1 + Tasks 2, 3, 4
// Read the updated data to verify all dependent tasks moved
const updatedData = readJSON(testTasksPath, null, 'backlog');
const rawData = updatedData._rawTaggedData || updatedData;
// Verify all tasks moved from backlog
expect(rawData.backlog?.tasks || []).toHaveLength(0); // All tasks moved
// Verify all tasks are now in in-progress
expect(rawData['in-progress']?.tasks || []).toHaveLength(5); // Task 5 + Tasks 1, 2, 3, 4
// Verify dependency relationships are preserved
const task1 = rawData['in-progress']?.tasks?.find((t) => t.id === 1);
const task2 = rawData['in-progress']?.tasks?.find((t) => t.id === 2);
const task3 = rawData['in-progress']?.tasks?.find((t) => t.id === 3);
const task4 = rawData['in-progress']?.tasks?.find((t) => t.id === 4);
expect(task1?.dependencies).toEqual([2, 3]);
expect(task2?.dependencies).toEqual([4]);
expect(task3?.dependencies).toEqual([]);
expect(task4?.dependencies).toEqual([]);
});
it('should handle circular dependency detection using actual move functions', async () => {
// Create data with circular dependencies
const circularData = {
backlog: {
tasks: [
{ id: 1, title: 'Task 1', dependencies: [2], status: 'pending' },
{ id: 2, title: 'Task 2', dependencies: [3], status: 'pending' },
{ id: 3, title: 'Task 3', dependencies: [1], status: 'pending' } // Circular dependency
]
},
'in-progress': {
tasks: [
{ id: 4, title: 'Task 4', dependencies: [], status: 'in-progress' }
]
}
};
// Set up mock file system with circular dependency data
mockFs({
[testDataDir]: {
'tasks.json': JSON.stringify(circularData, null, 2)
}
});
// Attempt to move Task 1 with dependencies should fail due to circular dependency
await expect(
moveTasksBetweenTags(
testTasksPath,
['1'],
'backlog',
'in-progress',
{ withDependencies: true, ignoreDependencies: false },
{ projectRoot: testDataDir }
)
).rejects.toThrow();
});
it('should handle nested dependency chains using actual move functions', async () => {
// Create data with nested dependency chains
const nestedData = {
backlog: {
tasks: [
{ id: 1, title: 'Task 1', dependencies: [2], status: 'pending' },
{ id: 2, title: 'Task 2', dependencies: [3], status: 'pending' },
{ id: 3, title: 'Task 3', dependencies: [4], status: 'pending' },
{ id: 4, title: 'Task 4', dependencies: [], status: 'pending' }
]
},
'in-progress': {
tasks: [
{ id: 5, title: 'Task 5', dependencies: [], status: 'in-progress' }
]
}
};
// Set up mock file system with nested dependency data
mockFs({
[testDataDir]: {
'tasks.json': JSON.stringify(nestedData, null, 2)
}
});
// Test moving Task 1 with all its nested dependencies
const result = await moveTasksBetweenTags(
testTasksPath,
['1'], // Task 1
'backlog',
'in-progress',
{ withDependencies: true, ignoreDependencies: false },
{ projectRoot: testDataDir }
);
// Verify the move operation was successful
expect(result).toBeDefined();
expect(result.message).toContain(
'Successfully moved 4 tasks from "backlog" to "in-progress"'
);
expect(result.movedTasks).toHaveLength(4); // Tasks 1, 2, 3, 4
// Read the updated data to verify all tasks moved
const updatedData = readJSON(testTasksPath, null, 'backlog');
const rawData = updatedData._rawTaggedData || updatedData;
// Verify all tasks moved from backlog
expect(rawData.backlog?.tasks || []).toHaveLength(0); // All tasks moved
// Verify all tasks are now in in-progress
expect(rawData['in-progress']?.tasks || []).toHaveLength(5); // Task 5 + Tasks 1, 2, 3, 4
// Verify dependency relationships are preserved
const task1 = rawData['in-progress']?.tasks?.find((t) => t.id === 1);
const task2 = rawData['in-progress']?.tasks?.find((t) => t.id === 2);
const task3 = rawData['in-progress']?.tasks?.find((t) => t.id === 3);
const task4 = rawData['in-progress']?.tasks?.find((t) => t.id === 4);
expect(task1?.dependencies).toEqual([2]);
expect(task2?.dependencies).toEqual([3]);
expect(task3?.dependencies).toEqual([4]);
expect(task4?.dependencies).toEqual([]);
});
it('should handle cross-tag dependency resolution using actual move functions', async () => {
// Create data with cross-tag dependencies
const crossTagData = {
backlog: {
tasks: [
{ id: 1, title: 'Task 1', dependencies: [5], status: 'pending' }, // Depends on task in in-progress
{ id: 2, title: 'Task 2', dependencies: [], status: 'pending' }
]
},
'in-progress': {
tasks: [
{ id: 5, title: 'Task 5', dependencies: [], status: 'in-progress' }
]
}
};
// Set up mock file system with cross-tag dependency data
mockFs({
[testDataDir]: {
'tasks.json': JSON.stringify(crossTagData, null, 2)
}
});
// Test moving Task 1 which depends on Task 5 in another tag
const result = await moveTasksBetweenTags(
testTasksPath,
['1'], // Task 1
'backlog',
'in-progress',
{ withDependencies: false, ignoreDependencies: false },
{ projectRoot: testDataDir }
);
// Verify the move operation was successful
expect(result).toBeDefined();
expect(result.message).toContain(
'Successfully moved 1 tasks from "backlog" to "in-progress"'
);
// Read the updated data to verify the move actually happened
const updatedData = readJSON(testTasksPath, null, 'backlog');
const rawData = updatedData._rawTaggedData || updatedData;
// Verify Task 1 is no longer in backlog
const taskInBacklog = rawData.backlog?.tasks?.find((t) => t.id === 1);
expect(taskInBacklog).toBeUndefined();
// Verify Task 1 is now in in-progress with its dependency preserved
const taskInProgress = rawData['in-progress']?.tasks?.find(
(t) => t.id === 1
);
expect(taskInProgress).toBeDefined();
expect(taskInProgress.title).toBe('Task 1');
expect(taskInProgress.dependencies).toEqual([5]); // Cross-tag dependency preserved
});
});
});
```
--------------------------------------------------------------------------------
/scripts/modules/task-manager/update-task-by-id.js:
--------------------------------------------------------------------------------
```javascript
import fs from 'fs';
import chalk from 'chalk';
import boxen from 'boxen';
import Table from 'cli-table3';
import {
readJSON,
writeJSON,
truncate,
flattenTasksWithSubtasks,
findProjectRoot
} from '../utils.js';
import {
getStatusWithColor,
startLoadingIndicator,
stopLoadingIndicator,
displayAiUsageSummary
} from '../ui.js';
import {
generateTextService,
generateObjectService
} from '../ai-services-unified.js';
import { COMMAND_SCHEMAS } from '../../../src/schemas/registry.js';
import {
isApiKeySet,
hasCodebaseAnalysis,
getDebugFlag
} from '../config-manager.js';
import { getPromptManager } from '../prompt-manager.js';
import { ContextGatherer } from '../utils/contextGatherer.js';
import { FuzzyTaskSearch } from '../utils/fuzzyTaskSearch.js';
import { tryUpdateViaRemote } from '@tm/bridge';
import { createBridgeLogger } from '../bridge-utils.js';
/**
* Update a task by ID with new information using the unified AI service.
* @param {string} tasksPath - Path to the tasks.json file
* @param {string|number} taskId - ID of the task to update (supports numeric, alphanumeric like HAM-123, and subtask IDs like 1.2)
* @param {string} prompt - Prompt for generating updated task information
* @param {boolean} [useResearch=false] - Whether to use the research AI role.
* @param {Object} context - Context object containing session and mcpLog.
* @param {Object} [context.session] - Session object from MCP server.
* @param {Object} [context.mcpLog] - MCP logger object.
* @param {string} [context.projectRoot] - Project root path.
* @param {string} [context.tag] - Tag for the task
* @param {string} [outputFormat='text'] - Output format ('text' or 'json').
* @param {boolean} [appendMode=false] - If true, append to details instead of full update.
* @returns {Promise<Object|null>} - The updated task or null if update failed.
*/
async function updateTaskById(
tasksPath,
taskId,
prompt,
useResearch = false,
context = {},
outputFormat = 'text',
appendMode = false
) {
const { session, mcpLog, projectRoot: providedProjectRoot, tag } = context;
const { report, isMCP } = createBridgeLogger(mcpLog, session);
try {
report('info', `Updating single task ${taskId} with prompt: "${prompt}"`);
// --- Input Validations ---
// Note: taskId can be a number (1), string with dot (1.2), or display ID (HAM-123)
// So we don't validate it as strictly anymore
if (taskId === null || taskId === undefined || String(taskId).trim() === '')
throw new Error('Task ID cannot be empty.');
if (!prompt || typeof prompt !== 'string' || prompt.trim() === '')
throw new Error('Prompt cannot be empty.');
// Determine project root first (needed for API key checks)
const projectRoot = providedProjectRoot || findProjectRoot();
if (!projectRoot) {
throw new Error('Could not determine project root directory');
}
if (useResearch && !isApiKeySet('perplexity', session)) {
report(
'warn',
'Perplexity research requested but API key not set. Falling back.'
);
if (outputFormat === 'text')
console.log(
chalk.yellow('Perplexity AI not available. Falling back to main AI.')
);
useResearch = false;
}
// --- BRIDGE: Try remote update first (API storage) ---
const remoteResult = await tryUpdateViaRemote({
taskId,
prompt,
projectRoot,
tag,
appendMode,
useResearch,
isMCP,
outputFormat,
report
});
// If remote handled it, return the result
if (remoteResult) {
return remoteResult;
}
// Otherwise fall through to file-based logic below
// --- End BRIDGE ---
// For file storage, ensure the tasks file exists
if (!fs.existsSync(tasksPath))
throw new Error(`Tasks file not found: ${tasksPath}`);
// --- End Input Validations ---
// --- Task Loading and Status Check (Keep existing) ---
const data = readJSON(tasksPath, projectRoot, tag);
if (!data || !data.tasks)
throw new Error(`No valid tasks found in ${tasksPath}.`);
// File storage requires a strict numeric task ID
const idStr = String(taskId).trim();
if (!/^\d+$/.test(idStr)) {
throw new Error(
'For file storage, taskId must be a positive integer. ' +
'Use update-subtask-by-id for IDs like "1.2", or run in API storage for display IDs (e.g., "HAM-123").'
);
}
const numericTaskId = Number(idStr);
const taskIndex = data.tasks.findIndex((task) => task.id === numericTaskId);
if (taskIndex === -1) {
report('error', `Task with ID ${numericTaskId} not found`);
throw new Error(`Task with ID ${numericTaskId} not found.`);
}
const taskToUpdate = data.tasks[taskIndex];
if (taskToUpdate.status === 'done' || taskToUpdate.status === 'completed') {
report(
'warn',
`Task ${taskId} is already marked as done and cannot be updated`
);
// Only show warning box for text output (CLI)
if (outputFormat === 'text') {
console.log(
boxen(
chalk.yellow(
`Task ${taskId} is already marked as ${taskToUpdate.status} and cannot be updated.`
) +
'\n\n' +
chalk.white(
'Completed tasks are locked to maintain consistency. To modify a completed task, you must first:'
) +
'\n' +
chalk.white(
'1. Change its status to "pending" or "in-progress"'
) +
'\n' +
chalk.white('2. Then run the update-task command'),
{ padding: 1, borderColor: 'yellow', borderStyle: 'round' }
)
);
}
return null;
}
// --- End Task Loading ---
// --- Context Gathering ---
let gatheredContext = '';
try {
const contextGatherer = new ContextGatherer(projectRoot, tag);
const allTasksFlat = flattenTasksWithSubtasks(data.tasks);
const fuzzySearch = new FuzzyTaskSearch(allTasksFlat, 'update-task');
const searchQuery = `${taskToUpdate.title} ${taskToUpdate.description} ${prompt}`;
const searchResults = fuzzySearch.findRelevantTasks(searchQuery, {
maxResults: 5,
includeSelf: true
});
const relevantTaskIds = fuzzySearch.getTaskIds(searchResults);
const finalTaskIds = [
...new Set([taskId.toString(), ...relevantTaskIds])
];
if (finalTaskIds.length > 0) {
const contextResult = await contextGatherer.gather({
tasks: finalTaskIds,
format: 'research'
});
gatheredContext = contextResult.context || '';
}
} catch (contextError) {
report('warn', `Could not gather context: ${contextError.message}`);
}
// --- End Context Gathering ---
// --- Display Task Info (CLI Only - Keep existing) ---
if (outputFormat === 'text') {
// Show the task that will be updated
const table = new Table({
head: [
chalk.cyan.bold('ID'),
chalk.cyan.bold('Title'),
chalk.cyan.bold('Status')
],
colWidths: [5, 60, 10]
});
table.push([
taskToUpdate.id,
truncate(taskToUpdate.title, 57),
getStatusWithColor(taskToUpdate.status)
]);
console.log(
boxen(chalk.white.bold(`Updating Task #${taskId}`), {
padding: 1,
borderColor: 'blue',
borderStyle: 'round',
margin: { top: 1, bottom: 0 }
})
);
console.log(table.toString());
// Display a message about how completed subtasks are handled
console.log(
boxen(
chalk.cyan.bold('How Completed Subtasks Are Handled:') +
'\n\n' +
chalk.white(
'• Subtasks marked as "done" or "completed" will be preserved\n'
) +
chalk.white(
'• New subtasks will build upon what has already been completed\n'
) +
chalk.white(
'• If completed work needs revision, a new subtask will be created instead of modifying done items\n'
) +
chalk.white(
'• This approach maintains a clear record of completed work and new requirements'
),
{
padding: 1,
borderColor: 'blue',
borderStyle: 'round',
margin: { top: 1, bottom: 1 }
}
)
);
}
// --- Build Prompts using PromptManager ---
const promptManager = getPromptManager();
const promptParams = {
task: taskToUpdate,
taskJson: JSON.stringify(taskToUpdate, null, 2),
updatePrompt: prompt,
appendMode: appendMode,
useResearch: useResearch,
currentDetails: taskToUpdate.details || '(No existing details)',
gatheredContext: gatheredContext || '',
hasCodebaseAnalysis: hasCodebaseAnalysis(
useResearch,
projectRoot,
session
),
projectRoot: projectRoot
};
const variantKey = appendMode
? 'append'
: useResearch
? 'research'
: 'default';
report(
'info',
`Loading prompt template with variant: ${variantKey}, appendMode: ${appendMode}, useResearch: ${useResearch}`
);
let systemPrompt;
let userPrompt;
try {
const promptResult = promptManager.loadPrompt(
'update-task',
promptParams,
variantKey
);
report(
'info',
`Prompt result type: ${typeof promptResult}, keys: ${promptResult ? Object.keys(promptResult).join(', ') : 'null'}`
);
// Extract prompts - loadPrompt returns { systemPrompt, userPrompt, metadata }
systemPrompt = promptResult.systemPrompt;
userPrompt = promptResult.userPrompt;
report(
'info',
`Loaded prompts - systemPrompt length: ${systemPrompt?.length}, userPrompt length: ${userPrompt?.length}`
);
} catch (error) {
report('error', `Failed to load prompt template: ${error.message}`);
throw new Error(`Failed to load prompt template: ${error.message}`);
}
// If prompts are still not set, throw an error
if (!systemPrompt || !userPrompt) {
throw new Error(
`Failed to load prompts: systemPrompt=${!!systemPrompt}, userPrompt=${!!userPrompt}`
);
}
// --- End Build Prompts ---
let loadingIndicator = null;
let aiServiceResponse = null;
if (!isMCP && outputFormat === 'text') {
loadingIndicator = startLoadingIndicator(
useResearch ? 'Updating task with research...\n' : 'Updating task...\n'
);
}
try {
const serviceRole = useResearch ? 'research' : 'main';
if (appendMode) {
// Append mode still uses generateTextService since it returns plain text
aiServiceResponse = await generateTextService({
role: serviceRole,
session: session,
projectRoot: projectRoot,
systemPrompt: systemPrompt,
prompt: userPrompt,
commandName: 'update-task',
outputType: isMCP ? 'mcp' : 'cli'
});
} else {
// Full update mode uses generateObjectService for structured output
aiServiceResponse = await generateObjectService({
role: serviceRole,
session: session,
projectRoot: projectRoot,
systemPrompt: systemPrompt,
prompt: userPrompt,
schema: COMMAND_SCHEMAS['update-task-by-id'],
objectName: 'task',
commandName: 'update-task',
outputType: isMCP ? 'mcp' : 'cli'
});
}
if (loadingIndicator)
stopLoadingIndicator(loadingIndicator, 'AI update complete.');
if (appendMode) {
// Append mode: handle as plain text
const generatedContentString = aiServiceResponse.mainResult;
let newlyAddedSnippet = '';
if (generatedContentString && generatedContentString.trim()) {
const timestamp = new Date().toISOString();
const formattedBlock = `<info added on ${timestamp}>\n${generatedContentString.trim()}\n</info added on ${timestamp}>`;
newlyAddedSnippet = formattedBlock;
// Append to task details
taskToUpdate.details =
(taskToUpdate.details ? taskToUpdate.details + '\n' : '') +
formattedBlock;
} else {
report(
'warn',
'AI response was empty or whitespace after trimming. Original details remain unchanged.'
);
newlyAddedSnippet = 'No new details were added by the AI.';
}
// Update description with timestamp if prompt is short
if (prompt.length < 100) {
if (taskToUpdate.description) {
taskToUpdate.description += ` [Updated: ${new Date().toLocaleDateString()}]`;
}
}
// Write the updated task back to file
data.tasks[taskIndex] = taskToUpdate;
writeJSON(tasksPath, data, projectRoot, tag);
report('success', `Successfully appended to task ${taskId}`);
// Display success message for CLI
if (outputFormat === 'text') {
console.log(
boxen(
chalk.green(`Successfully appended to task #${taskId}`) +
'\n\n' +
chalk.white.bold('Title:') +
' ' +
taskToUpdate.title +
'\n\n' +
chalk.white.bold('Newly Added Content:') +
'\n' +
chalk.white(newlyAddedSnippet),
{ padding: 1, borderColor: 'green', borderStyle: 'round' }
)
);
}
// Display AI usage telemetry for CLI users
if (outputFormat === 'text' && aiServiceResponse.telemetryData) {
displayAiUsageSummary(aiServiceResponse.telemetryData, 'cli');
}
// Return the updated task
return {
updatedTask: taskToUpdate,
telemetryData: aiServiceResponse.telemetryData,
tagInfo: aiServiceResponse.tagInfo
};
}
// Full update mode: Use structured data directly
const updatedTask = aiServiceResponse.mainResult.task;
// --- Task Validation/Correction (Keep existing logic) ---
if (!updatedTask || typeof updatedTask !== 'object')
throw new Error('Received invalid task object from AI.');
if (!updatedTask.title || !updatedTask.description)
throw new Error('Updated task missing required fields.');
// Preserve ID if AI changed it
if (updatedTask.id !== taskId) {
report('warn', `AI changed task ID. Restoring original ID ${taskId}.`);
updatedTask.id = taskId;
}
// Preserve status if AI changed it
if (
updatedTask.status !== taskToUpdate.status &&
!prompt.toLowerCase().includes('status')
) {
report(
'warn',
`AI changed task status. Restoring original status '${taskToUpdate.status}'.`
);
updatedTask.status = taskToUpdate.status;
}
// Fix subtask IDs if they exist (ensure they are numeric and sequential)
if (updatedTask.subtasks && Array.isArray(updatedTask.subtasks)) {
let currentSubtaskId = 1;
updatedTask.subtasks = updatedTask.subtasks.map((subtask) => {
// Fix AI-generated subtask IDs that might be strings or use parent ID as prefix
const correctedSubtask = {
...subtask,
id: currentSubtaskId, // Override AI-generated ID with correct sequential ID
dependencies: Array.isArray(subtask.dependencies)
? subtask.dependencies
.map((dep) =>
typeof dep === 'string' ? parseInt(dep, 10) : dep
)
.filter(
(depId) =>
!Number.isNaN(depId) &&
depId >= 1 &&
depId < currentSubtaskId
)
: [],
status: subtask.status || 'pending'
};
currentSubtaskId++;
return correctedSubtask;
});
report(
'info',
`Fixed ${updatedTask.subtasks.length} subtask IDs to be sequential numeric IDs.`
);
}
// Preserve completed subtasks (Keep existing logic)
if (taskToUpdate.subtasks?.length > 0) {
if (!updatedTask.subtasks) {
report(
'warn',
'Subtasks removed by AI. Restoring original subtasks.'
);
updatedTask.subtasks = taskToUpdate.subtasks;
} else {
const completedOriginal = taskToUpdate.subtasks.filter(
(st) => st.status === 'done' || st.status === 'completed'
);
completedOriginal.forEach((compSub) => {
const updatedSub = updatedTask.subtasks.find(
(st) => st.id === compSub.id
);
if (
!updatedSub ||
JSON.stringify(updatedSub) !== JSON.stringify(compSub)
) {
report(
'warn',
`Completed subtask ${compSub.id} was modified or removed. Restoring.`
);
// Remove potentially modified version
updatedTask.subtasks = updatedTask.subtasks.filter(
(st) => st.id !== compSub.id
);
// Add back original
updatedTask.subtasks.push(compSub);
}
});
// Deduplicate just in case
const subtaskIds = new Set();
updatedTask.subtasks = updatedTask.subtasks.filter((st) => {
if (!subtaskIds.has(st.id)) {
subtaskIds.add(st.id);
return true;
}
report('warn', `Duplicate subtask ID ${st.id} removed.`);
return false;
});
}
}
// --- End Task Validation/Correction ---
// --- Update Task Data (Keep existing) ---
data.tasks[taskIndex] = updatedTask;
// --- End Update Task Data ---
// --- Write File and Generate (Unchanged) ---
writeJSON(tasksPath, data, projectRoot, tag);
report('success', `Successfully updated task ${taskId}`);
// await generateTaskFiles(tasksPath, path.dirname(tasksPath));
// --- End Write File ---
// --- Display CLI Telemetry ---
if (outputFormat === 'text' && aiServiceResponse.telemetryData) {
displayAiUsageSummary(aiServiceResponse.telemetryData, 'cli'); // <<< ADD display
}
// --- Return Success with Telemetry ---
return {
updatedTask: updatedTask, // Return the updated task object
telemetryData: aiServiceResponse.telemetryData, // <<< ADD telemetryData
tagInfo: aiServiceResponse.tagInfo
};
} catch (error) {
// Catch errors from generateTextService
if (loadingIndicator) stopLoadingIndicator(loadingIndicator);
report('error', `Error during AI service call: ${error.message}`);
if (error.message.includes('API key')) {
report('error', 'Please ensure API keys are configured correctly.');
}
throw error; // Re-throw error
}
} catch (error) {
// General error catch
// --- General Error Handling (Keep existing) ---
report('error', `Error updating task: ${error.message}`);
if (outputFormat === 'text') {
console.error(chalk.red(`Error: ${error.message}`));
// ... helpful hints ...
if (getDebugFlag(session)) console.error(error);
process.exit(1);
}
throw error; // Re-throw for MCP
// --- End General Error Handling ---
}
}
export default updateTaskById;
```
--------------------------------------------------------------------------------
/README-task-master.md:
--------------------------------------------------------------------------------
```markdown
# Task Master
### by [@eyaltoledano](https://x.com/eyaltoledano)
A task management system for AI-driven development with Claude, designed to work seamlessly with Cursor AI.
## Requirements
- Node.js 14.0.0 or higher
- Anthropic API key (Claude API)
- Anthropic SDK version 0.39.0 or higher
- OpenAI SDK (for Perplexity API integration, optional)
## Configuration
Taskmaster uses two primary configuration methods:
1. **`.taskmasterconfig` File (Project Root)**
- Stores most settings: AI model selections (main, research, fallback), parameters (max tokens, temperature), logging level, default priority/subtasks, project name.
- **Created and managed using `task-master models --setup` CLI command or the `models` MCP tool.**
- Do not edit manually unless you know what you are doing.
2. **Environment Variables (`.env` file or MCP `env` block)**
- Used **only** for sensitive **API Keys** (e.g., `ANTHROPIC_API_KEY`, `PERPLEXITY_API_KEY`, etc.) and specific endpoints (like `OLLAMA_BASE_URL`).
- **For CLI:** Place keys in a `.env` file in your project root.
- **For MCP/Cursor:** Place keys in the `env` section of your `.cursor/mcp.json` (or other MCP config according to the AI IDE or client you use) file under the `taskmaster-ai` server definition.
**Important:** Settings like model choices, max tokens, temperature, and log level are **no longer configured via environment variables.** Use the `task-master models` command or tool.
See the [Configuration Guide](docs/configuration.md) for full details.
## Installation
```bash
# Install globally
npm install -g task-master-ai
# OR install locally within your project
npm install task-master-ai
```
### Initialize a new project
```bash
# If installed globally
task-master init
# If installed locally
npx task-master init
```
This will prompt you for project details and set up a new project with the necessary files and structure.
### Important Notes
1. **ES Modules Configuration:**
- This project uses ES Modules (ESM) instead of CommonJS.
- This is set via `"type": "module"` in your package.json.
- Use `import/export` syntax instead of `require()`.
- Files should use `.js` or `.mjs` extensions.
- To use a CommonJS module, either:
- Rename it with `.cjs` extension
- Use `await import()` for dynamic imports
- If you need CommonJS throughout your project, remove `"type": "module"` from package.json, but Task Master scripts expect ESM.
2. The Anthropic SDK version should be 0.39.0 or higher.
## Quick Start with Global Commands
After installing the package globally, you can use these CLI commands from any directory:
```bash
# Initialize a new project
task-master init
# Parse a PRD and generate tasks
task-master parse-prd your-prd.txt
# List all tasks
task-master list
# Show the next task to work on
task-master next
# Generate task files
task-master generate
```
## Troubleshooting
### If `task-master init` doesn't respond:
Try running it with Node directly:
```bash
node node_modules/claude-task-master/scripts/init.js
```
Or clone the repository and run:
```bash
git clone https://github.com/eyaltoledano/claude-task-master.git
cd claude-task-master
node scripts/init.js
```
## Task Structure
Tasks in tasks.json have the following structure:
- `id`: Unique identifier for the task (Example: `1`)
- `title`: Brief, descriptive title of the task (Example: `"Initialize Repo"`)
- `description`: Concise description of what the task involves (Example: `"Create a new repository, set up initial structure."`)
- `status`: Current state of the task (Example: `"pending"`, `"done"`, `"deferred"`)
- `dependencies`: IDs of tasks that must be completed before this task (Example: `[1, 2]`)
- Dependencies are displayed with status indicators (✅ for completed, ⏱️ for pending)
- This helps quickly identify which prerequisite tasks are blocking work
- `priority`: Importance level of the task (Example: `"high"`, `"medium"`, `"low"`)
- `details`: In-depth implementation instructions (Example: `"Use GitHub client ID/secret, handle callback, set session token."`)
- `testStrategy`: Verification approach (Example: `"Deploy and call endpoint to confirm 'Hello World' response."`)
- `subtasks`: List of smaller, more specific tasks that make up the main task (Example: `[{"id": 1, "title": "Configure OAuth", ...}]`)
## Integrating with Cursor AI
Claude Task Master is designed to work seamlessly with [Cursor AI](https://www.cursor.so/), providing a structured workflow for AI-driven development.
### Setup with Cursor
1. After initializing your project, open it in Cursor
2. The `.cursor/rules/dev_workflow.mdc` file is automatically loaded by Cursor, providing the AI with knowledge about the task management system
3. Place your PRD document in the `scripts/` directory (e.g., `scripts/prd.txt`)
4. Open Cursor's AI chat and switch to Agent mode
### Setting up MCP in Cursor
To enable enhanced task management capabilities directly within Cursor using the Model Control Protocol (MCP):
1. Go to Cursor settings
2. Navigate to the MCP section
3. Click on "Add New MCP Server"
4. Configure with the following details:
- Name: "Task Master"
- Type: "Command"
- Command: "npx -y task-master-ai"
5. Save the settings
Once configured, you can interact with Task Master's task management commands directly through Cursor's interface, providing a more integrated experience.
### Initial Task Generation
In Cursor's AI chat, instruct the agent to generate tasks from your PRD:
```
Please use the task-master parse-prd command to generate tasks from my PRD. The PRD is located at scripts/prd.txt.
```
The agent will execute:
```bash
task-master parse-prd scripts/prd.txt
```
This will:
- Parse your PRD document
- Generate a structured `tasks.json` file with tasks, dependencies, priorities, and test strategies
- The agent will understand this process due to the Cursor rules
### Generate Individual Task Files
Next, ask the agent to generate individual task files:
```
Please generate individual task files from tasks.json
```
The agent will execute:
```bash
task-master generate
```
This creates individual task files in the `tasks/` directory (e.g., `task_001.txt`, `task_002.txt`), making it easier to reference specific tasks.
## AI-Driven Development Workflow
The Cursor agent is pre-configured (via the rules file) to follow this workflow:
### 1. Task Discovery and Selection
Ask the agent to list available tasks:
```
What tasks are available to work on next?
```
The agent will:
- Run `task-master list` to see all tasks
- Run `task-master next` to determine the next task to work on
- Analyze dependencies to determine which tasks are ready to be worked on
- Prioritize tasks based on priority level and ID order
- Suggest the next task(s) to implement
### 2. Task Implementation
When implementing a task, the agent will:
- Reference the task's details section for implementation specifics
- Consider dependencies on previous tasks
- Follow the project's coding standards
- Create appropriate tests based on the task's testStrategy
You can ask:
```
Let's implement task 3. What does it involve?
```
### 3. Task Verification
Before marking a task as complete, verify it according to:
- The task's specified testStrategy
- Any automated tests in the codebase
- Manual verification if required
### 4. Task Completion
When a task is completed, tell the agent:
```
Task 3 is now complete. Please update its status.
```
The agent will execute:
```bash
task-master set-status --id=3 --status=done
```
### 5. Handling Implementation Drift
If during implementation, you discover that:
- The current approach differs significantly from what was planned
- Future tasks need to be modified due to current implementation choices
- New dependencies or requirements have emerged
Tell the agent:
```
We've changed our approach. We're now using Express instead of Fastify. Please update all future tasks to reflect this change.
```
The agent will execute:
```bash
task-master update --from=4 --prompt="Now we are using Express instead of Fastify."
```
This will rewrite or re-scope subsequent tasks in tasks.json while preserving completed work.
### 6. Breaking Down Complex Tasks
For complex tasks that need more granularity:
```
Task 5 seems complex. Can you break it down into subtasks?
```
The agent will execute:
```bash
task-master expand --id=5 --num=3
```
You can provide additional context:
```
Please break down task 5 with a focus on security considerations.
```
The agent will execute:
```bash
task-master expand --id=5 --prompt="Focus on security aspects"
```
You can also expand all pending tasks:
```
Please break down all pending tasks into subtasks.
```
The agent will execute:
```bash
task-master expand --all
```
For research-backed subtask generation using Perplexity AI:
```
Please break down task 5 using research-backed generation.
```
The agent will execute:
```bash
task-master expand --id=5 --research
```
## Command Reference
Here's a comprehensive reference of all available commands:
### Parse PRD
```bash
# Parse a PRD file and generate tasks
task-master parse-prd <prd-file.txt>
# Limit the number of tasks generated (default is 10)
task-master parse-prd <prd-file.txt> --num-tasks=5
# Allow task master to determine the number of tasks based on complexity
task-master parse-prd <prd-file.txt> --num-tasks=0
```
### List Tasks
```bash
# List all tasks
task-master list
# List tasks with a specific status
task-master list --status=<status>
# List tasks with subtasks
task-master list --with-subtasks
# List tasks with a specific status and include subtasks
task-master list --status=<status> --with-subtasks
```
### Show Next Task
```bash
# Show the next task to work on based on dependencies and status
task-master next
```
### Show Specific Task
```bash
# Show details of a specific task
task-master show <id>
# or
task-master show --id=<id>
# View a specific subtask (e.g., subtask 2 of task 1)
task-master show 1.2
```
### Update Tasks
```bash
# Update tasks from a specific ID and provide context
task-master update --from=<id> --prompt="<prompt>"
```
### Generate Task Files
```bash
# Generate individual task files from tasks.json
task-master generate
```
### Set Task Status
```bash
# Set status of a single task
task-master set-status --id=<id> --status=<status>
# Set status for multiple tasks
task-master set-status --id=1,2,3 --status=<status>
# Set status for subtasks
task-master set-status --id=1.1,1.2 --status=<status>
```
When marking a task as "done", all of its subtasks will automatically be marked as "done" as well.
### Expand Tasks
```bash
# Expand a specific task with subtasks
task-master expand --id=<id> --num=<number>
# Expand a task with a dynamic number of subtasks (ignoring complexity report)
task-master expand --id=<id> --num=0
# Expand with additional context
task-master expand --id=<id> --prompt="<context>"
# Expand all pending tasks
task-master expand --all
# Force regeneration of subtasks for tasks that already have them
task-master expand --all --force
# Research-backed subtask generation for a specific task
task-master expand --id=<id> --research
# Research-backed generation for all tasks
task-master expand --all --research
```
### Clear Subtasks
```bash
# Clear subtasks from a specific task
task-master clear-subtasks --id=<id>
# Clear subtasks from multiple tasks
task-master clear-subtasks --id=1,2,3
# Clear subtasks from all tasks
task-master clear-subtasks --all
```
### Analyze Task Complexity
```bash
# Analyze complexity of all tasks
task-master analyze-complexity
# Save report to a custom location
task-master analyze-complexity --output=my-report.json
# Use a specific LLM model
task-master analyze-complexity --model=claude-3-opus-20240229
# Set a custom complexity threshold (1-10)
task-master analyze-complexity --threshold=6
# Use an alternative tasks file
task-master analyze-complexity --file=custom-tasks.json
# Use Perplexity AI for research-backed complexity analysis
task-master analyze-complexity --research
```
### View Complexity Report
```bash
# Display the task complexity analysis report
task-master complexity-report
# View a report at a custom location
task-master complexity-report --file=my-report.json
```
### Managing Task Dependencies
```bash
# Add a dependency to a task
task-master add-dependency --id=<id> --depends-on=<id>
# Remove a dependency from a task
task-master remove-dependency --id=<id> --depends-on=<id>
# Validate dependencies without fixing them
task-master validate-dependencies
# Find and fix invalid dependencies automatically
task-master fix-dependencies
```
### Add a New Task
```bash
# Add a new task using AI
task-master add-task --prompt="Description of the new task"
# Add a task with dependencies
task-master add-task --prompt="Description" --dependencies=1,2,3
# Add a task with priority
task-master add-task --prompt="Description" --priority=high
```
## Feature Details
### Analyzing Task Complexity
The `analyze-complexity` command:
- Analyzes each task using AI to assess its complexity on a scale of 1-10
- Recommends optimal number of subtasks based on configured DEFAULT_SUBTASKS
- Generates tailored prompts for expanding each task
- Creates a comprehensive JSON report with ready-to-use commands
- Saves the report to scripts/task-complexity-report.json by default
The generated report contains:
- Complexity analysis for each task (scored 1-10)
- Recommended number of subtasks based on complexity
- AI-generated expansion prompts customized for each task
- Ready-to-run expansion commands directly within each task analysis
### Viewing Complexity Report
The `complexity-report` command:
- Displays a formatted, easy-to-read version of the complexity analysis report
- Shows tasks organized by complexity score (highest to lowest)
- Provides complexity distribution statistics (low, medium, high)
- Highlights tasks recommended for expansion based on threshold score
- Includes ready-to-use expansion commands for each complex task
- If no report exists, offers to generate one on the spot
### Smart Task Expansion
The `expand` command automatically checks for and uses the complexity report:
When a complexity report exists:
- Tasks are automatically expanded using the recommended subtask count and prompts
- When expanding all tasks, they're processed in order of complexity (highest first)
- Research-backed generation is preserved from the complexity analysis
- You can still override recommendations with explicit command-line options
Example workflow:
```bash
# Generate the complexity analysis report with research capabilities
task-master analyze-complexity --research
# Review the report in a readable format
task-master complexity-report
# Expand tasks using the optimized recommendations
task-master expand --id=8
# or expand all tasks
task-master expand --all
```
### Finding the Next Task
The `next` command:
- Identifies tasks that are pending/in-progress and have all dependencies satisfied
- Prioritizes tasks by priority level, dependency count, and task ID
- Displays comprehensive information about the selected task:
- Basic task details (ID, title, priority, dependencies)
- Implementation details
- Subtasks (if they exist)
- Provides contextual suggested actions:
- Command to mark the task as in-progress
- Command to mark the task as done
- Commands for working with subtasks
### Viewing Specific Task Details
The `show` command:
- Displays comprehensive details about a specific task or subtask
- Shows task status, priority, dependencies, and detailed implementation notes
- For parent tasks, displays all subtasks and their status
- For subtasks, shows parent task relationship
- Provides contextual action suggestions based on the task's state
- Works with both regular tasks and subtasks (using the format taskId.subtaskId)
## Best Practices for AI-Driven Development
1. **Start with a detailed PRD**: The more detailed your PRD, the better the generated tasks will be.
2. **Review generated tasks**: After parsing the PRD, review the tasks to ensure they make sense and have appropriate dependencies.
3. **Analyze task complexity**: Use the complexity analysis feature to identify which tasks should be broken down further.
4. **Follow the dependency chain**: Always respect task dependencies - the Cursor agent will help with this.
5. **Update as you go**: If your implementation diverges from the plan, use the update command to keep future tasks aligned with your current approach.
6. **Break down complex tasks**: Use the expand command to break down complex tasks into manageable subtasks.
7. **Regenerate task files**: After any updates to tasks.json, regenerate the task files to keep them in sync.
8. **Communicate context to the agent**: When asking the Cursor agent to help with a task, provide context about what you're trying to achieve.
9. **Validate dependencies**: Periodically run the validate-dependencies command to check for invalid or circular dependencies.
## Example Cursor AI Interactions
### Starting a new project
```
I've just initialized a new project with Claude Task Master. I have a PRD at scripts/prd.txt.
Can you help me parse it and set up the initial tasks?
```
### Working on tasks
```
What's the next task I should work on? Please consider dependencies and priorities.
```
### Implementing a specific task
```
I'd like to implement task 4. Can you help me understand what needs to be done and how to approach it?
```
### Managing subtasks
```
I need to regenerate the subtasks for task 3 with a different approach. Can you help me clear and regenerate them?
```
### Handling changes
```
We've decided to use MongoDB instead of PostgreSQL. Can you update all future tasks to reflect this change?
```
### Completing work
```
I've finished implementing the authentication system described in task 2. All tests are passing.
Please mark it as complete and tell me what I should work on next.
```
### Analyzing complexity
```
Can you analyze the complexity of our tasks to help me understand which ones need to be broken down further?
```
### Viewing complexity report
```
Can you show me the complexity report in a more readable format?
```
```
--------------------------------------------------------------------------------
/.taskmaster/docs/task-template-importing-prd.txt:
--------------------------------------------------------------------------------
```
# Task Template Importing System - Product Requirements Document
<context>
# Overview
The Task Template Importing system enables seamless integration of external task templates into the Task Master CLI through automatic file discovery. This system allows users to drop task template files into the tasks directory and immediately access them as new tag contexts without manual import commands or configuration. The solution addresses the need for multi-project task management, team collaboration through shared templates, and clean separation between permanent tasks and temporary project contexts.
# Core Features
## Silent Task Template Discovery
- **What it does**: Automatically scans for `tasks_*.json` files in the tasks directory during tag operations
- **Why it's important**: Eliminates friction in adding new task contexts and enables zero-configuration workflow
- **How it works**: File pattern matching extracts tag names from filenames and validates against internal tag keys
## External Tag Resolution System
- **What it does**: Provides fallback mechanism to external files when tags are not found in main tasks.json
- **Why it's important**: Maintains clean separation between core tasks and project-specific templates
- **How it works**: Tag resolution logic checks external files as secondary source while preserving main file precedence
## Read-Only External Tag Access
- **What it does**: Allows viewing and switching to external tags while preventing modifications
- **Why it's important**: Protects template integrity and prevents accidental changes to shared templates
- **How it works**: All task modifications route to main tasks.json regardless of current tag context
## Tag Precedence Management
- **What it does**: Ensures main tasks.json tags override external files with same tag names
- **Why it's important**: Prevents conflicts and maintains data integrity
- **How it works**: Priority system where main file tags take precedence over external file tags
# User Experience
## User Personas
- **Solo Developer**: Manages multiple projects with different task contexts
- **Team Lead**: Shares standardized task templates across team members
- **Project Manager**: Organizes tasks by project phases or feature branches
## Key User Flows
### Template Addition Flow
1. User receives or creates a `tasks_projectname.json` file
2. User drops file into `.taskmaster/tasks/` directory
3. Tag becomes immediately available via `task-master use-tag projectname`
4. User can list, view, and switch to external tag without configuration
### Template Usage Flow
1. User runs `task-master tags` to see available tags including external ones
2. External tags display with `(imported)` indicator
3. User switches to external tag with `task-master use-tag projectname`
4. User can view tasks but modifications are routed to main tasks.json
## UI/UX Considerations
- External tags clearly marked with `(imported)` suffix in listings
- Visual indicators distinguish between main and external tags
- Error messages guide users when external files are malformed
- Read-only warnings when attempting to modify external tag contexts
</context>
<PRD>
# Technical Architecture
## System Components
1. **External File Discovery Engine**
- File pattern scanner for `tasks_*.json` files
- Tag name extraction from filenames using regex
- Dynamic tag registry combining main and external sources
- Error handling for malformed external files
2. **Enhanced Tag Resolution System**
- Fallback mechanism to external files when tags not found in main tasks.json
- Precedence management ensuring main file tags override external files
- Read-only access enforcement for external tags
- Tag metadata preservation during discovery operations
3. **Silent Discovery Integration**
- Automatic scanning during tag-related operations
- Seamless integration with existing tag management functions
- Zero-configuration workflow requiring no manual import commands
- Dynamic tag availability without restart requirements
## Data Models
### External Task File Structure
```json
{
"meta": {
"projectName": "External Project Name",
"version": "1.0.0",
"templateSource": "external",
"createdAt": "ISO-8601 timestamp"
},
"tags": {
"projectname": {
"meta": {
"name": "Project Name",
"description": "Project description",
"createdAt": "ISO-8601 timestamp"
},
"tasks": [
// Array of task objects
]
},
"master": {
// This section is ignored to prevent conflicts
}
}
}
```
### Enhanced Tag Registry Model
```json
{
"mainTags": [
{
"name": "master",
"source": "main",
"taskCount": 150,
"isActive": true
}
],
"externalTags": [
{
"name": "projectname",
"source": "external",
"filename": "tasks_projectname.json",
"taskCount": 25,
"isReadOnly": true
}
]
}
```
## APIs and Integrations
1. **File System Discovery API**
- Directory scanning with pattern matching
- JSON file validation and parsing
- Error handling for corrupted or malformed files
- File modification time tracking for cache invalidation
2. **Enhanced Tag Management API**
- `scanForExternalTaskFiles(projectRoot)` - Discover external template files
- `getExternalTagsFromFiles(projectRoot)` - Extract tag names from external files
- `readExternalTagData(projectRoot, tagName)` - Read specific external tag data
- `getAvailableTags(projectRoot)` - Combined main and external tag listing
3. **Tag Resolution Enhancement**
- Modified `readJSON()` with external file fallback
- Enhanced `tags()` function with external tag display
- Updated `useTag()` function supporting external tag switching
- Read-only enforcement for external tag operations
## Infrastructure Requirements
1. **File System Access**
- Read permissions for tasks directory
- JSON parsing capabilities
- Pattern matching and regex support
- Error handling for file system operations
2. **Backward Compatibility**
- Existing tag operations continue unchanged
- Main tasks.json structure preserved
- No breaking changes to current workflows
- Graceful degradation when external files unavailable
# Development Roadmap
## Phase 1: Core External File Discovery (Foundation)
1. **External File Scanner Implementation**
- Create `scanForExternalTaskFiles()` function in utils.js
- Implement file pattern matching for `tasks_*.json` files
- Add error handling for file system access issues
- Test with various filename patterns and edge cases
2. **Tag Name Extraction System**
- Implement `getExternalTagsFromFiles()` function
- Create regex pattern for extracting tag names from filenames
- Add validation to ensure tag names match internal tag key format
- Handle special characters and invalid filename patterns
3. **External Tag Data Reader**
- Create `readExternalTagData()` function
- Implement JSON parsing with error handling
- Add validation for required tag structure
- Ignore 'master' key in external files to prevent conflicts
## Phase 2: Tag Resolution Enhancement (Core Integration)
1. **Enhanced Tag Registry**
- Implement `getAvailableTags()` function combining main and external sources
- Create tag metadata structure including source information
- Add deduplication logic prioritizing main tags over external
- Implement caching mechanism for performance optimization
2. **Modified readJSON Function**
- Add external file fallback when tag not found in main tasks.json
- Maintain precedence rule: main tasks.json overrides external files
- Preserve existing error handling and validation patterns
- Ensure read-only access for external tags
3. **Tag Listing Enhancement**
- Update `tags()` function to display external tags with `(imported)` indicator
- Show external tag metadata and task counts
- Maintain current tag highlighting and sorting functionality
- Add visual distinction between main and external tags
## Phase 3: User Interface Integration (User Experience)
1. **Tag Switching Enhancement**
- Update `useTag()` function to support external tag switching
- Add read-only warnings when switching to external tags
- Update state.json with external tag context information
- Maintain current tag switching behavior for main tags
2. **Error Handling and User Feedback**
- Implement comprehensive error messages for malformed external files
- Add user guidance for proper external file structure
- Create warnings for read-only operations on external tags
- Ensure graceful degradation when external files are corrupted
3. **Documentation and Help Integration**
- Update command help text to include external tag information
- Add examples of external file structure and usage
- Create troubleshooting guide for common external file issues
- Document file naming conventions and best practices
## Phase 4: Advanced Features and Optimization (Enhancement)
1. **Performance Optimization**
- Implement file modification time caching
- Add lazy loading for external tag data
- Optimize file scanning for directories with many files
- Create efficient tag resolution caching mechanism
2. **Advanced External File Features**
- Support for nested external file directories
- Batch external file validation and reporting
- External file metadata display and management
- Integration with version control ignore patterns
3. **Team Collaboration Features**
- Shared external file validation
- External file conflict detection and resolution
- Team template sharing guidelines and documentation
- Integration with git workflows for template management
# Logical Dependency Chain
## Foundation Layer (Must Be Built First)
1. **External File Scanner**
- Core requirement for all other functionality
- Provides the discovery mechanism for external template files
- Must handle file system access and pattern matching reliably
2. **Tag Name Extraction**
- Depends on file scanner functionality
- Required for identifying available external tags
- Must validate tag names against internal format requirements
3. **External Tag Data Reader**
- Depends on tag name extraction
- Provides access to external tag content
- Must handle JSON parsing and validation safely
## Integration Layer (Builds on Foundation)
4. **Enhanced Tag Registry**
- Depends on all foundation components
- Combines main and external tag sources
- Required for unified tag management across the system
5. **Modified readJSON Function**
- Depends on enhanced tag registry
- Provides fallback mechanism for tag resolution
- Critical for maintaining backward compatibility
6. **Tag Listing Enhancement**
- Depends on enhanced tag registry
- Provides user visibility into external tags
- Required for user discovery of available templates
## User Experience Layer (Completes the Feature)
7. **Tag Switching Enhancement**
- Depends on modified readJSON and tag listing
- Enables user interaction with external tags
- Must enforce read-only access properly
8. **Error Handling and User Feedback**
- Can be developed in parallel with other UX components
- Enhances reliability and user experience
- Should be integrated throughout development process
9. **Documentation and Help Integration**
- Should be developed alongside implementation
- Required for user adoption and proper usage
- Can be completed in parallel with advanced features
## Optimization Layer (Performance and Advanced Features)
10. **Performance Optimization**
- Can be developed after core functionality is stable
- Improves user experience with large numbers of external files
- Not blocking for initial release
11. **Advanced External File Features**
- Can be developed independently after core features
- Enhances power user workflows
- Optional for initial release
12. **Team Collaboration Features**
- Depends on stable core functionality
- Enhances team workflows and template sharing
- Can be prioritized based on user feedback
# Risks and Mitigations
## Technical Challenges
### File System Performance
**Risk**: Scanning for external files on every tag operation could impact performance with large directories.
**Mitigation**:
- Implement file modification time caching to avoid unnecessary rescans
- Use lazy loading for external tag data - only read when accessed
- Add configurable limits on number of external files to scan
- Optimize file pattern matching with efficient regex patterns
### External File Corruption
**Risk**: Malformed or corrupted external JSON files could break tag operations.
**Mitigation**:
- Implement robust JSON parsing with comprehensive error handling
- Add file validation before attempting to parse external files
- Gracefully skip corrupted files and continue with valid ones
- Provide clear error messages guiding users to fix malformed files
### Tag Name Conflicts
**Risk**: External files might contain tag names that conflict with main tasks.json tags.
**Mitigation**:
- Implement strict precedence rule: main tasks.json always overrides external files
- Add warnings when external tags are ignored due to conflicts
- Document naming conventions to avoid common conflicts
- Provide validation tools to check for potential conflicts
## MVP Definition
### Core Feature Scope
**Risk**: Including too many advanced features could delay the core functionality.
**Mitigation**:
- Define MVP as basic external file discovery + tag switching
- Focus on the silent discovery mechanism as the primary value proposition
- Defer advanced features like nested directories and batch operations
- Ensure each phase delivers complete, usable functionality
### User Experience Complexity
**Risk**: The read-only nature of external tags might confuse users.
**Mitigation**:
- Provide clear visual indicators for external tags in all interfaces
- Add explicit warnings when users attempt to modify external tag contexts
- Document the read-only behavior and its rationale clearly
- Consider future enhancement for external tag modification workflows
### Backward Compatibility
**Risk**: Changes to tag resolution logic might break existing workflows.
**Mitigation**:
- Maintain existing tag operations unchanged for main tasks.json
- Add external file support as enhancement, not replacement
- Test thoroughly with existing task structures and workflows
- Provide migration path if any breaking changes are necessary
## Resource Constraints
### Development Complexity
**Risk**: Integration with existing tag management system could be complex.
**Mitigation**:
- Phase implementation to minimize risk of breaking existing functionality
- Create comprehensive test suite covering both main and external tag scenarios
- Use feature flags to enable/disable external file support during development
- Implement thorough error handling to prevent system failures
### File System Dependencies
**Risk**: Different operating systems might handle file operations differently.
**Mitigation**:
- Use Node.js built-in file system APIs for cross-platform compatibility
- Test on multiple operating systems (Windows, macOS, Linux)
- Handle file path separators and naming conventions properly
- Add fallback mechanisms for file system access issues
### User Adoption
**Risk**: Users might not understand or adopt the external file template system.
**Mitigation**:
- Create clear documentation with practical examples
- Provide sample external template files for common use cases
- Integrate help and guidance directly into the CLI interface
- Gather user feedback early and iterate on the user experience
# Appendix
## External File Naming Convention
### Filename Pattern
- **Format**: `tasks_[tagname].json`
- **Examples**: `tasks_feature-auth.json`, `tasks_v2-migration.json`, `tasks_project-alpha.json`
- **Validation**: Tag name must match internal tag key format (alphanumeric, hyphens, underscores)
### File Structure Requirements
```json
{
"meta": {
"projectName": "Required: Human-readable project name",
"version": "Optional: Template version",
"templateSource": "Optional: Source identifier",
"createdAt": "Optional: ISO-8601 timestamp"
},
"tags": {
"[tagname]": {
"meta": {
"name": "Required: Tag display name",
"description": "Optional: Tag description",
"createdAt": "Optional: ISO-8601 timestamp"
},
"tasks": [
// Required: Array of task objects following standard task structure
]
}
}
}
```
## Implementation Functions Specification
### Core Discovery Functions
```javascript
// Scan tasks directory for external template files
function scanForExternalTaskFiles(projectRoot) {
// Returns: Array of external file paths
}
// Extract tag names from external filenames
function getExternalTagsFromFiles(projectRoot) {
// Returns: Array of external tag names
}
// Read specific external tag data
function readExternalTagData(projectRoot, tagName) {
// Returns: Tag data object or null if not found
}
// Get combined main and external tags
function getAvailableTags(projectRoot) {
// Returns: Combined tag registry with metadata
}
```
### Integration Points
```javascript
// Enhanced readJSON with external fallback
function readJSON(projectRoot, tag = null) {
// Modified to check external files when tag not found in main
}
// Enhanced tags listing with external indicators
function tags(projectRoot, options = {}) {
// Modified to display external tags with (imported) suffix
}
// Enhanced tag switching with external support
function useTag(projectRoot, tagName) {
// Modified to support switching to external tags (read-only)
}
```
## Error Handling Specifications
### File System Errors
- **ENOENT**: External file not found - gracefully skip and continue
- **EACCES**: Permission denied - warn user and continue with available files
- **EISDIR**: Directory instead of file - skip and continue scanning
### JSON Parsing Errors
- **SyntaxError**: Malformed JSON - skip file and log warning with filename
- **Missing required fields**: Skip file and provide specific error message
- **Invalid tag structure**: Skip file and guide user to correct format
### Tag Conflict Resolution
- **Duplicate tag names**: Main tasks.json takes precedence, log warning
- **Invalid tag names**: Skip external file and provide naming guidance
- **Master key in external**: Ignore master key, process other tags normally
</PRD>
```
--------------------------------------------------------------------------------
/tests/unit/ai-providers/base-provider.test.js:
--------------------------------------------------------------------------------
```javascript
import { jest } from '@jest/globals';
// Mock the 'ai' SDK
const mockGenerateText = jest.fn();
const mockGenerateObject = jest.fn();
const mockNoObjectGeneratedError = class NoObjectGeneratedError extends Error {
static isInstance(error) {
return error instanceof mockNoObjectGeneratedError;
}
constructor(cause) {
super('No object generated');
this.cause = cause;
this.usage = cause.usage;
}
};
const mockJSONParseError = class JSONParseError extends Error {
constructor(text) {
super('JSON parse error');
this.text = text;
}
};
jest.unstable_mockModule('ai', () => ({
generateText: mockGenerateText,
streamText: jest.fn(),
generateObject: mockGenerateObject,
streamObject: jest.fn(),
zodSchema: jest.fn((schema) => schema),
NoObjectGeneratedError: mockNoObjectGeneratedError,
JSONParseError: mockJSONParseError
}));
// Mock jsonrepair
const mockJsonrepair = jest.fn();
jest.unstable_mockModule('jsonrepair', () => ({
jsonrepair: mockJsonrepair
}));
// Mock logging and utilities
jest.unstable_mockModule('../../../scripts/modules/utils.js', () => ({
log: jest.fn(),
findProjectRoot: jest.fn(() => '/mock/project/root'),
isEmpty: jest.fn(
(val) =>
!val ||
(Array.isArray(val) && val.length === 0) ||
(typeof val === 'object' && Object.keys(val).length === 0)
),
resolveEnvVariable: jest.fn((key) => process.env[key])
}));
// Import after mocking
const { BaseAIProvider } = await import(
'../../../src/ai-providers/base-provider.js'
);
describe('BaseAIProvider', () => {
let testProvider;
let mockClient;
beforeEach(() => {
// Create a concrete test provider
class TestProvider extends BaseAIProvider {
constructor() {
super();
this.name = 'TestProvider';
}
getRequiredApiKeyName() {
return 'TEST_API_KEY';
}
async getClient() {
return mockClient;
}
}
mockClient = jest.fn((modelId) => ({ modelId }));
jest.clearAllMocks();
testProvider = new TestProvider();
});
describe('1. Parameter Validation - Catches Invalid Inputs', () => {
describe('validateAuth', () => {
it('should throw when API key is missing', () => {
expect(() => testProvider.validateAuth({})).toThrow(
'TestProvider API key is required'
);
});
it('should pass when API key is provided', () => {
expect(() =>
testProvider.validateAuth({ apiKey: 'test-key' })
).not.toThrow();
});
});
describe('validateParams', () => {
it('should throw when model ID is missing', () => {
expect(() => testProvider.validateParams({ apiKey: 'key' })).toThrow(
'TestProvider Model ID is required'
);
});
it('should throw when both API key and model ID are missing', () => {
expect(() => testProvider.validateParams({})).toThrow(
'TestProvider API key is required'
);
});
});
describe('validateOptionalParams', () => {
it('should throw for temperature below 0', () => {
expect(() =>
testProvider.validateOptionalParams({ temperature: -0.1 })
).toThrow('Temperature must be between 0 and 1');
});
it('should throw for temperature above 1', () => {
expect(() =>
testProvider.validateOptionalParams({ temperature: 1.1 })
).toThrow('Temperature must be between 0 and 1');
});
it('should accept temperature at boundaries', () => {
expect(() =>
testProvider.validateOptionalParams({ temperature: 0 })
).not.toThrow();
expect(() =>
testProvider.validateOptionalParams({ temperature: 1 })
).not.toThrow();
});
it('should throw for invalid maxTokens values', () => {
expect(() =>
testProvider.validateOptionalParams({ maxTokens: 0 })
).toThrow('maxTokens must be a finite number greater than 0');
expect(() =>
testProvider.validateOptionalParams({ maxTokens: -100 })
).toThrow('maxTokens must be a finite number greater than 0');
expect(() =>
testProvider.validateOptionalParams({ maxTokens: Infinity })
).toThrow('maxTokens must be a finite number greater than 0');
expect(() =>
testProvider.validateOptionalParams({ maxTokens: 'invalid' })
).toThrow('maxTokens must be a finite number greater than 0');
});
});
describe('validateMessages', () => {
it('should throw for null/undefined messages', async () => {
await expect(
testProvider.generateText({
apiKey: 'key',
modelId: 'model',
messages: null
})
).rejects.toThrow('Invalid or empty messages array provided');
await expect(
testProvider.generateText({
apiKey: 'key',
modelId: 'model',
messages: undefined
})
).rejects.toThrow('Invalid or empty messages array provided');
});
it('should throw for empty messages array', async () => {
await expect(
testProvider.generateText({
apiKey: 'key',
modelId: 'model',
messages: []
})
).rejects.toThrow('Invalid or empty messages array provided');
});
it('should throw for messages without role or content', async () => {
await expect(
testProvider.generateText({
apiKey: 'key',
modelId: 'model',
messages: [{ content: 'test' }] // missing role
})
).rejects.toThrow(
'Invalid message format. Each message must have role and content'
);
await expect(
testProvider.generateText({
apiKey: 'key',
modelId: 'model',
messages: [{ role: 'user' }] // missing content
})
).rejects.toThrow(
'Invalid message format. Each message must have role and content'
);
});
});
});
describe('2. Error Handling - Proper Error Context', () => {
it('should wrap API errors with context', async () => {
const apiError = new Error('API rate limit exceeded');
mockGenerateText.mockRejectedValue(apiError);
await expect(
testProvider.generateText({
apiKey: 'key',
modelId: 'model',
messages: [{ role: 'user', content: 'test' }]
})
).rejects.toThrow(
'TestProvider API error during text generation: API rate limit exceeded'
);
});
it('should handle errors without message property', async () => {
const apiError = { code: 'NETWORK_ERROR' };
mockGenerateText.mockRejectedValue(apiError);
await expect(
testProvider.generateText({
apiKey: 'key',
modelId: 'model',
messages: [{ role: 'user', content: 'test' }]
})
).rejects.toThrow(
'TestProvider API error during text generation: Unknown error occurred'
);
});
});
describe('3. Abstract Class Protection', () => {
it('should prevent direct instantiation of BaseAIProvider', () => {
expect(() => new BaseAIProvider()).toThrow(
'BaseAIProvider cannot be instantiated directly'
);
});
it('should throw when abstract methods are not implemented', () => {
class IncompleteProvider extends BaseAIProvider {
constructor() {
super();
}
}
const provider = new IncompleteProvider();
expect(() => provider.getClient()).toThrow(
'getClient must be implemented by provider'
);
expect(() => provider.getRequiredApiKeyName()).toThrow(
'getRequiredApiKeyName must be implemented by provider'
);
});
});
describe('4. Token Parameter Preparation', () => {
it('should convert maxTokens to maxOutputTokens as integer', () => {
const result = testProvider.prepareTokenParam('model', 1000.7);
expect(result).toEqual({ maxOutputTokens: 1000 });
});
it('should handle string numbers', () => {
const result = testProvider.prepareTokenParam('model', '500');
expect(result).toEqual({ maxOutputTokens: 500 });
});
it('should return empty object when maxTokens is undefined', () => {
const result = testProvider.prepareTokenParam('model', undefined);
expect(result).toEqual({});
});
it('should floor decimal values', () => {
const result = testProvider.prepareTokenParam('model', 999.99);
expect(result).toEqual({ maxOutputTokens: 999 });
});
});
describe('5. JSON Repair for Malformed Responses', () => {
it('should repair malformed JSON in generateObject errors', async () => {
const malformedJson = '{"key": "value",,}'; // Double comma
const repairedJson = '{"key": "value"}';
const parseError = new mockJSONParseError(malformedJson);
const noObjectError = new mockNoObjectGeneratedError(parseError);
noObjectError.usage = {
promptTokens: 100,
completionTokens: 50,
totalTokens: 150
};
mockGenerateObject.mockRejectedValue(noObjectError);
mockJsonrepair.mockReturnValue(repairedJson);
const result = await testProvider.generateObject({
apiKey: 'key',
modelId: 'model',
messages: [{ role: 'user', content: 'test' }],
schema: { type: 'object' },
objectName: 'TestObject'
});
expect(mockJsonrepair).toHaveBeenCalledWith(malformedJson);
expect(result).toEqual({
object: { key: 'value' },
usage: {
inputTokens: 100,
outputTokens: 50,
totalTokens: 150
}
});
});
it('should throw original error when JSON repair fails', async () => {
const malformedJson = 'not even close to JSON';
const parseError = new mockJSONParseError(malformedJson);
const noObjectError = new mockNoObjectGeneratedError(parseError);
mockGenerateObject.mockRejectedValue(noObjectError);
mockJsonrepair.mockImplementation(() => {
throw new Error('Cannot repair this JSON');
});
await expect(
testProvider.generateObject({
apiKey: 'key',
modelId: 'model',
messages: [{ role: 'user', content: 'test' }],
schema: { type: 'object' },
objectName: 'TestObject'
})
).rejects.toThrow('TestProvider API error during object generation');
});
it('should handle non-JSON parse errors normally', async () => {
const regularError = new Error('Network timeout');
mockGenerateObject.mockRejectedValue(regularError);
await expect(
testProvider.generateObject({
apiKey: 'key',
modelId: 'model',
messages: [{ role: 'user', content: 'test' }],
schema: { type: 'object' },
objectName: 'TestObject'
})
).rejects.toThrow(
'TestProvider API error during object generation: Network timeout'
);
expect(mockJsonrepair).not.toHaveBeenCalled();
});
});
describe('6. Usage Token Normalization', () => {
it('should normalize different token formats in generateText', async () => {
// Test promptTokens/completionTokens format (older format)
mockGenerateText.mockResolvedValue({
text: 'response',
usage: { promptTokens: 10, completionTokens: 5 }
});
let result = await testProvider.generateText({
apiKey: 'key',
modelId: 'model',
messages: [{ role: 'user', content: 'test' }]
});
expect(result.usage).toEqual({
inputTokens: 10,
outputTokens: 5,
totalTokens: 15
});
// Test inputTokens/outputTokens format (newer format)
mockGenerateText.mockResolvedValue({
text: 'response',
usage: { inputTokens: 20, outputTokens: 10, totalTokens: 30 }
});
result = await testProvider.generateText({
apiKey: 'key',
modelId: 'model',
messages: [{ role: 'user', content: 'test' }]
});
expect(result.usage).toEqual({
inputTokens: 20,
outputTokens: 10,
totalTokens: 30
});
});
it('should handle missing usage data gracefully', async () => {
mockGenerateText.mockResolvedValue({
text: 'response',
usage: undefined
});
const result = await testProvider.generateText({
apiKey: 'key',
modelId: 'model',
messages: [{ role: 'user', content: 'test' }]
});
expect(result.usage).toEqual({
inputTokens: 0,
outputTokens: 0,
totalTokens: 0
});
});
it('should calculate totalTokens when missing', async () => {
mockGenerateText.mockResolvedValue({
text: 'response',
usage: { inputTokens: 15, outputTokens: 25 }
});
const result = await testProvider.generateText({
apiKey: 'key',
modelId: 'model',
messages: [{ role: 'user', content: 'test' }]
});
expect(result.usage.totalTokens).toBe(40);
});
});
describe('7. Schema Validation for Object Methods', () => {
it('should throw when schema is missing for generateObject', async () => {
await expect(
testProvider.generateObject({
apiKey: 'key',
modelId: 'model',
messages: [{ role: 'user', content: 'test' }],
objectName: 'TestObject'
// missing schema
})
).rejects.toThrow('Schema is required for object generation');
});
it('should throw when objectName is missing for generateObject', async () => {
await expect(
testProvider.generateObject({
apiKey: 'key',
modelId: 'model',
messages: [{ role: 'user', content: 'test' }],
schema: { type: 'object' }
// missing objectName
})
).rejects.toThrow('Object name is required for object generation');
});
it('should throw when schema is missing for streamObject', async () => {
await expect(
testProvider.streamObject({
apiKey: 'key',
modelId: 'model',
messages: [{ role: 'user', content: 'test' }]
// missing schema
})
).rejects.toThrow('Schema is required for object streaming');
});
it('should use json mode when needsExplicitJsonSchema is true', async () => {
testProvider.needsExplicitJsonSchema = true;
mockGenerateObject.mockResolvedValue({
object: { test: 'value' },
usage: { inputTokens: 10, outputTokens: 5, totalTokens: 15 }
});
await testProvider.generateObject({
apiKey: 'key',
modelId: 'model',
messages: [{ role: 'user', content: 'test' }],
schema: { type: 'object' },
objectName: 'TestObject'
});
expect(mockGenerateObject).toHaveBeenCalledWith(
expect.objectContaining({
mode: 'json' // Should be 'json' not 'auto'
})
);
});
});
describe('8. Integration Points - Client Creation', () => {
it('should pass params to getClient method', async () => {
const getClientSpy = jest.spyOn(testProvider, 'getClient');
mockGenerateText.mockResolvedValue({
text: 'response',
usage: { inputTokens: 10, outputTokens: 5, totalTokens: 15 }
});
const params = {
apiKey: 'test-key',
modelId: 'test-model',
messages: [{ role: 'user', content: 'test' }],
customParam: 'custom-value'
};
await testProvider.generateText(params);
expect(getClientSpy).toHaveBeenCalledWith(params);
});
it('should use client with correct model ID', async () => {
mockGenerateText.mockResolvedValue({
text: 'response',
usage: { inputTokens: 10, outputTokens: 5, totalTokens: 15 }
});
await testProvider.generateText({
apiKey: 'key',
modelId: 'gpt-4-turbo',
messages: [{ role: 'user', content: 'test' }]
});
expect(mockClient).toHaveBeenCalledWith('gpt-4-turbo');
expect(mockGenerateText).toHaveBeenCalledWith(
expect.objectContaining({
model: { modelId: 'gpt-4-turbo' }
})
);
});
});
describe('9. Edge Cases - Boundary Conditions', () => {
it('should handle zero maxTokens gracefully', () => {
// This should throw in validation
expect(() =>
testProvider.validateOptionalParams({ maxTokens: 0 })
).toThrow('maxTokens must be a finite number greater than 0');
});
it('should handle very large maxTokens', () => {
const result = testProvider.prepareTokenParam('model', 999999999);
expect(result).toEqual({ maxOutputTokens: 999999999 });
});
it('should handle NaN temperature gracefully', () => {
// NaN fails the range check (NaN < 0 is false, NaN > 1 is also false)
// But NaN is not between 0 and 1, so we need to check the actual behavior
// The current implementation doesn't explicitly check for NaN,
// it passes because NaN < 0 and NaN > 1 are both false
expect(() =>
testProvider.validateOptionalParams({ temperature: NaN })
).not.toThrow();
// This is actually a bug - NaN should be rejected
// But we're testing current behavior, not desired behavior
});
it('should handle concurrent calls safely', async () => {
mockGenerateText.mockImplementation(async () => ({
text: 'response',
usage: { inputTokens: 10, outputTokens: 5, totalTokens: 15 }
}));
const promises = Array.from({ length: 10 }, (_, i) =>
testProvider.generateText({
apiKey: 'key',
modelId: `model-${i}`,
messages: [{ role: 'user', content: `test-${i}` }]
})
);
const results = await Promise.all(promises);
expect(results).toHaveLength(10);
expect(mockClient).toHaveBeenCalledTimes(10);
});
});
describe('10. Default Behavior - isRequiredApiKey', () => {
it('should return true by default for isRequiredApiKey', () => {
expect(testProvider.isRequiredApiKey()).toBe(true);
});
it('should allow override of isRequiredApiKey', () => {
class NoAuthProvider extends BaseAIProvider {
constructor() {
super();
}
isRequiredApiKey() {
return false;
}
validateAuth() {
// Override to not require API key
}
getClient() {
return mockClient;
}
getRequiredApiKeyName() {
return null;
}
}
const provider = new NoAuthProvider();
expect(provider.isRequiredApiKey()).toBe(false);
});
});
describe('11. Temperature Filtering - CLI vs Standard Providers', () => {
const mockStreamText = jest.fn();
const mockStreamObject = jest.fn();
beforeEach(() => {
mockStreamText.mockReset();
mockStreamObject.mockReset();
});
it('should include temperature in generateText when supported', async () => {
testProvider.supportsTemperature = true;
mockGenerateText.mockResolvedValue({
text: 'response',
usage: { inputTokens: 10, outputTokens: 5, totalTokens: 15 }
});
await testProvider.generateText({
apiKey: 'key',
modelId: 'model',
messages: [{ role: 'user', content: 'test' }],
temperature: 0.7
});
expect(mockGenerateText).toHaveBeenCalledWith(
expect.objectContaining({ temperature: 0.7 })
);
});
it('should exclude temperature in generateText when not supported', async () => {
testProvider.supportsTemperature = false;
mockGenerateText.mockResolvedValue({
text: 'response',
usage: { inputTokens: 10, outputTokens: 5, totalTokens: 15 }
});
await testProvider.generateText({
apiKey: 'key',
modelId: 'model',
messages: [{ role: 'user', content: 'test' }],
temperature: 0.7
});
const callArgs = mockGenerateText.mock.calls[0][0];
expect(callArgs).not.toHaveProperty('temperature');
});
it('should exclude temperature when undefined even if supported', async () => {
testProvider.supportsTemperature = true;
mockGenerateText.mockResolvedValue({
text: 'response',
usage: { inputTokens: 10, outputTokens: 5, totalTokens: 15 }
});
await testProvider.generateText({
apiKey: 'key',
modelId: 'model',
messages: [{ role: 'user', content: 'test' }],
temperature: undefined
});
const callArgs = mockGenerateText.mock.calls[0][0];
expect(callArgs).not.toHaveProperty('temperature');
});
});
});
```
--------------------------------------------------------------------------------
/src/ai-providers/gemini-cli.js:
--------------------------------------------------------------------------------
```javascript
/**
* src/ai-providers/gemini-cli.js
*
* Implementation for interacting with Gemini models via Gemini CLI
* using the ai-sdk-provider-gemini-cli package.
*/
import { generateObject, generateText, streamText } from 'ai';
import { parse } from 'jsonc-parser';
import { BaseAIProvider } from './base-provider.js';
import { log } from '../../scripts/modules/utils.js';
import { createGeminiProvider } from 'ai-sdk-provider-gemini-cli';
export class GeminiCliProvider extends BaseAIProvider {
constructor() {
super();
this.name = 'Gemini CLI';
// Gemini CLI requires explicit JSON schema mode
this.needsExplicitJsonSchema = true;
// Gemini CLI does not support temperature parameter
this.supportsTemperature = false;
}
/**
* Override validateAuth to handle Gemini CLI authentication options
* @param {object} params - Parameters to validate
*/
validateAuth(params) {
// Gemini CLI is designed to use pre-configured OAuth authentication
// Users choose gemini-cli specifically to leverage their existing
// gemini auth login credentials, not to use API keys.
// We support API keys for compatibility, but the expected usage
// is through CLI authentication (no API key required).
// No validation needed - the SDK will handle auth internally
}
/**
* Creates and returns a Gemini CLI client instance.
* @param {object} params - Parameters for client initialization
* @param {string} [params.apiKey] - Optional Gemini API key (rarely used with gemini-cli)
* @param {string} [params.baseURL] - Optional custom API endpoint
* @returns {Promise<Function>} Gemini CLI client function
* @throws {Error} If initialization fails
*/
async getClient(params) {
try {
// Primary use case: Use existing gemini CLI authentication
// Secondary use case: Direct API key (for compatibility)
let authOptions = {};
if (params.apiKey && params.apiKey !== 'gemini-cli-no-key-required') {
// API key provided - use it for compatibility
authOptions = {
authType: 'api-key',
apiKey: params.apiKey
};
} else {
// Expected case: Use gemini CLI authentication via OAuth
authOptions = {
authType: 'oauth-personal'
};
}
// Add baseURL if provided (for custom endpoints)
if (params.baseURL) {
authOptions.baseURL = params.baseURL;
}
// Create and return the provider
return createGeminiProvider(authOptions);
} catch (error) {
this.handleError('client initialization', error);
}
}
/**
* Extracts system messages from the messages array and returns them separately.
* This is needed because ai-sdk-provider-gemini-cli expects system prompts as a separate parameter.
* @param {Array} messages - Array of message objects
* @param {Object} options - Options for system prompt enhancement
* @param {boolean} options.enforceJsonOutput - Whether to add JSON enforcement to system prompt
* @returns {Object} - {systemPrompt: string|undefined, messages: Array}
*/
_extractSystemMessage(messages, options = {}) {
if (!messages || !Array.isArray(messages)) {
return { systemPrompt: undefined, messages: messages || [] };
}
const systemMessages = messages.filter((msg) => msg.role === 'system');
const nonSystemMessages = messages.filter((msg) => msg.role !== 'system');
// Combine multiple system messages if present
let systemPrompt =
systemMessages.length > 0
? systemMessages.map((msg) => msg.content).join('\n\n')
: undefined;
// Add Gemini CLI specific JSON enforcement if requested
if (options.enforceJsonOutput) {
const jsonEnforcement = this._getJsonEnforcementPrompt();
systemPrompt = systemPrompt
? `${systemPrompt}\n\n${jsonEnforcement}`
: jsonEnforcement;
}
return { systemPrompt, messages: nonSystemMessages };
}
/**
* Gets a Gemini CLI specific system prompt to enforce strict JSON output
* @returns {string} JSON enforcement system prompt
*/
_getJsonEnforcementPrompt() {
return `CRITICAL: You MUST respond with ONLY valid JSON. Do not include any explanatory text, markdown formatting, code block markers, or conversational phrases like "Here is" or "Of course". Your entire response must be parseable JSON that starts with { or [ and ends with } or ]. No exceptions.`;
}
/**
* Checks if a string is valid JSON
* @param {string} text - Text to validate
* @returns {boolean} True if valid JSON
*/
_isValidJson(text) {
if (!text || typeof text !== 'string') {
return false;
}
try {
JSON.parse(text.trim());
return true;
} catch {
return false;
}
}
/**
* Detects if the user prompt is requesting JSON output
* @param {Array} messages - Array of message objects
* @returns {boolean} True if JSON output is likely expected
*/
_detectJsonRequest(messages) {
const userMessages = messages.filter((msg) => msg.role === 'user');
const combinedText = userMessages
.map((msg) => msg.content)
.join(' ')
.toLowerCase();
// Look for indicators that JSON output is expected
const jsonIndicators = [
'json',
'respond only with',
'return only',
'output only',
'format:',
'structure:',
'schema:',
'{"',
'[{',
'subtasks',
'array',
'object'
];
return jsonIndicators.some((indicator) => combinedText.includes(indicator));
}
/**
* Simplifies complex prompts for gemini-cli to improve JSON output compliance
* @param {Array} messages - Array of message objects
* @returns {Array} Simplified messages array
*/
_simplifyJsonPrompts(messages) {
// First, check if this is an expand-task operation by looking at the system message
const systemMsg = messages.find((m) => m.role === 'system');
const isExpandTask =
systemMsg &&
systemMsg.content.includes(
'You are an AI assistant helping with task breakdown. Generate exactly'
);
if (!isExpandTask) {
return messages; // Not an expand task, return unchanged
}
// Extract subtask count from system message
const subtaskCountMatch = systemMsg.content.match(
/Generate exactly (\d+) subtasks/
);
const subtaskCount = subtaskCountMatch ? subtaskCountMatch[1] : '10';
log(
'debug',
`${this.name} detected expand-task operation, simplifying for ${subtaskCount} subtasks`
);
return messages.map((msg) => {
if (msg.role !== 'user') {
return msg;
}
// For expand-task user messages, create a much simpler, more direct prompt
// that doesn't depend on specific task content
const simplifiedPrompt = `Generate exactly ${subtaskCount} subtasks in the following JSON format.
CRITICAL INSTRUCTION: You must respond with ONLY valid JSON. No explanatory text, no "Here is", no "Of course", no markdown - just the JSON object.
Required JSON structure:
{
"subtasks": [
{
"id": 1,
"title": "Specific actionable task title",
"description": "Clear task description",
"dependencies": [],
"details": "Implementation details and guidance",
"testStrategy": "Testing approach"
}
]
}
Generate ${subtaskCount} subtasks based on the original task context. Return ONLY the JSON object.`;
log(
'debug',
`${this.name} simplified user prompt for better JSON compliance`
);
return { ...msg, content: simplifiedPrompt };
});
}
/**
* Extract JSON from Gemini's response using a tolerant parser.
*
* Optimized approach that progressively tries different parsing strategies:
* 1. Direct parsing after cleanup
* 2. Smart boundary detection with single-pass analysis
* 3. Limited character-by-character fallback for edge cases
*
* @param {string} text - Raw text which may contain JSON
* @returns {string} A valid JSON string if extraction succeeds, otherwise the original text
*/
extractJson(text) {
if (!text || typeof text !== 'string') {
return text;
}
let content = text.trim();
// Early exit for very short content
if (content.length < 2) {
return text;
}
// Strip common wrappers in a single pass
content = content
// Remove markdown fences
.replace(/^.*?```(?:json)?\s*([\s\S]*?)\s*```.*$/i, '$1')
// Remove variable declarations
.replace(/^\s*(?:const|let|var)\s+\w+\s*=\s*([\s\S]*?)(?:;|\s*)$/i, '$1')
// Remove common prefixes
.replace(/^(?:Here's|The)\s+(?:the\s+)?JSON.*?[:]\s*/i, '')
.trim();
// Find the first JSON-like structure
const firstObj = content.indexOf('{');
const firstArr = content.indexOf('[');
if (firstObj === -1 && firstArr === -1) {
return text;
}
const start =
firstArr === -1
? firstObj
: firstObj === -1
? firstArr
: Math.min(firstObj, firstArr);
content = content.slice(start);
// Optimized parsing function with error collection
const tryParse = (value) => {
if (!value || value.length < 2) return undefined;
const errors = [];
try {
const result = parse(value, errors, {
allowTrailingComma: true,
allowEmptyContent: false
});
if (errors.length === 0 && result !== undefined) {
return JSON.stringify(result, null, 2);
}
} catch {
// Parsing failed completely
}
return undefined;
};
// Try parsing the full content first
const fullParse = tryParse(content);
if (fullParse !== undefined) {
return fullParse;
}
// Smart boundary detection - single pass with optimizations
const openChar = content[0];
const closeChar = openChar === '{' ? '}' : ']';
let depth = 0;
let inString = false;
let escapeNext = false;
let lastValidEnd = -1;
// Single-pass boundary detection with early termination
for (let i = 0; i < content.length && i < 10000; i++) {
// Limit scan for performance
const char = content[i];
if (escapeNext) {
escapeNext = false;
continue;
}
if (char === '\\') {
escapeNext = true;
continue;
}
if (char === '"') {
inString = !inString;
continue;
}
if (inString) continue;
if (char === openChar) {
depth++;
} else if (char === closeChar) {
depth--;
if (depth === 0) {
lastValidEnd = i + 1;
// Try parsing immediately on first valid boundary
const candidate = content.slice(0, lastValidEnd);
const parsed = tryParse(candidate);
if (parsed !== undefined) {
return parsed;
}
}
}
}
// If we found valid boundaries but parsing failed, try limited fallback
if (lastValidEnd > 0) {
const maxAttempts = Math.min(5, Math.floor(lastValidEnd / 100)); // Limit attempts
for (let i = 0; i < maxAttempts; i++) {
const testEnd = Math.max(
lastValidEnd - i * 50,
Math.floor(lastValidEnd * 0.8)
);
const candidate = content.slice(0, testEnd);
const parsed = tryParse(candidate);
if (parsed !== undefined) {
return parsed;
}
}
}
return text;
}
/**
* Generates text using Gemini CLI model
* Overrides base implementation to properly handle system messages and enforce JSON output when needed
*/
async generateText(params) {
try {
this.validateParams(params);
this.validateMessages(params.messages);
log(
'debug',
`Generating ${this.name} text with model: ${params.modelId}`
);
// Detect if JSON output is expected and enforce it for better gemini-cli compatibility
const enforceJsonOutput = this._detectJsonRequest(params.messages);
// Debug logging to understand what's happening
log('debug', `${this.name} JSON detection analysis:`, {
enforceJsonOutput,
messageCount: params.messages.length,
messages: params.messages.map((msg) => ({
role: msg.role,
contentPreview: msg.content
? msg.content.substring(0, 200) + '...'
: 'empty'
}))
});
if (enforceJsonOutput) {
log(
'debug',
`${this.name} detected JSON request - applying strict JSON enforcement system prompt`
);
}
// For gemini-cli, simplify complex prompts before processing
let processedMessages = params.messages;
if (enforceJsonOutput) {
processedMessages = this._simplifyJsonPrompts(params.messages);
}
// Extract system messages for separate handling with optional JSON enforcement
const { systemPrompt, messages } = this._extractSystemMessage(
processedMessages,
{ enforceJsonOutput }
);
// Debug the final system prompt being sent
log('debug', `${this.name} final system prompt:`, {
systemPromptLength: systemPrompt ? systemPrompt.length : 0,
systemPromptPreview: systemPrompt
? systemPrompt.substring(0, 300) + '...'
: 'none',
finalMessageCount: messages.length
});
const client = await this.getClient(params);
const result = await generateText({
model: client(params.modelId),
system: systemPrompt,
messages: messages,
maxOutputTokens: params.maxTokens,
temperature: params.temperature
});
// If we detected a JSON request and gemini-cli returned conversational text,
// attempt to extract JSON from the response
let finalText = result.text;
if (enforceJsonOutput && result.text && !this._isValidJson(result.text)) {
log(
'debug',
`${this.name} response appears conversational, attempting JSON extraction`
);
// Log first 1000 chars of the response to see what Gemini actually returned
log('debug', `${this.name} raw response preview:`, {
responseLength: result.text.length,
responseStart: result.text.substring(0, 1000)
});
const extractedJson = this.extractJson(result.text);
if (this._isValidJson(extractedJson)) {
log(
'debug',
`${this.name} successfully extracted JSON from conversational response`
);
finalText = extractedJson;
} else {
log(
'debug',
`${this.name} JSON extraction failed, returning original response`
);
// Log what extraction returned to debug why it failed
log('debug', `${this.name} extraction result preview:`, {
extractedLength: extractedJson ? extractedJson.length : 0,
extractedStart: extractedJson
? extractedJson.substring(0, 500)
: 'null'
});
}
}
log(
'debug',
`${this.name} generateText completed successfully for model: ${params.modelId}`
);
return {
text: finalText,
usage: {
inputTokens: result.usage?.promptTokens,
outputTokens: result.usage?.completionTokens,
totalTokens: result.usage?.totalTokens
}
};
} catch (error) {
this.handleError('text generation', error);
}
}
/**
* Streams text using Gemini CLI model
* Overrides base implementation to properly handle system messages and enforce JSON output when needed
*/
async streamText(params) {
try {
this.validateParams(params);
this.validateMessages(params.messages);
log('debug', `Streaming ${this.name} text with model: ${params.modelId}`);
// Detect if JSON output is expected and enforce it for better gemini-cli compatibility
const enforceJsonOutput = this._detectJsonRequest(params.messages);
// Debug logging to understand what's happening
log('debug', `${this.name} JSON detection analysis:`, {
enforceJsonOutput,
messageCount: params.messages.length,
messages: params.messages.map((msg) => ({
role: msg.role,
contentPreview: msg.content
? msg.content.substring(0, 200) + '...'
: 'empty'
}))
});
if (enforceJsonOutput) {
log(
'debug',
`${this.name} detected JSON request - applying strict JSON enforcement system prompt`
);
}
// Extract system messages for separate handling with optional JSON enforcement
const { systemPrompt, messages } = this._extractSystemMessage(
params.messages,
{ enforceJsonOutput }
);
const client = await this.getClient(params);
const stream = await streamText({
model: client(params.modelId),
system: systemPrompt,
messages: messages,
maxOutputTokens: params.maxTokens,
temperature: params.temperature
});
log(
'debug',
`${this.name} streamText initiated successfully for model: ${params.modelId}`
);
// Note: For streaming, we can't intercept and modify the response in real-time
// The JSON extraction would need to happen on the consuming side
return stream;
} catch (error) {
this.handleError('text streaming', error);
}
}
/**
* Generates a structured object using Gemini CLI model
* Overrides base implementation to handle Gemini-specific JSON formatting issues and system messages
*/
async generateObject(params) {
try {
// First try the standard generateObject from base class
return await super.generateObject(params);
} catch (error) {
// If it's a JSON parsing error, try to extract and parse JSON manually
if (error.message?.includes('JSON') || error.message?.includes('parse')) {
log(
'debug',
`Gemini CLI generateObject failed with parsing error, attempting manual extraction`
);
try {
// Validate params first
this.validateParams(params);
this.validateMessages(params.messages);
if (!params.schema) {
throw new Error('Schema is required for object generation');
}
if (!params.objectName) {
throw new Error('Object name is required for object generation');
}
// Extract system messages for separate handling with JSON enforcement
const { systemPrompt, messages } = this._extractSystemMessage(
params.messages,
{ enforceJsonOutput: true }
);
// Call generateObject directly with our client
const client = await this.getClient(params);
const result = await generateObject({
model: client(params.modelId),
system: systemPrompt,
messages: messages,
schema: params.schema,
mode: this.needsExplicitJsonSchema ? 'json' : 'auto',
maxOutputTokens: params.maxTokens,
temperature: params.temperature
});
// If we get rawResponse text, try to extract JSON from it
if (result.rawResponse?.text && !result.object) {
const extractedJson = this.extractJson(result.rawResponse.text);
try {
result.object = JSON.parse(extractedJson);
} catch (parseError) {
log(
'error',
`Failed to parse extracted JSON: ${parseError.message}`
);
log(
'debug',
`Extracted JSON: ${extractedJson.substring(0, 500)}...`
);
throw new Error(
`Gemini CLI returned invalid JSON that could not be parsed: ${parseError.message}`
);
}
}
return {
object: result.object,
usage: {
inputTokens: result.usage?.promptTokens,
outputTokens: result.usage?.completionTokens,
totalTokens: result.usage?.totalTokens
}
};
} catch (retryError) {
log(
'error',
`Gemini CLI manual JSON extraction failed: ${retryError.message}`
);
// Re-throw the original error with more context
throw new Error(
`${this.name} failed to generate valid JSON object: ${error.message}`
);
}
}
// For non-parsing errors, just re-throw
throw error;
}
}
getRequiredApiKeyName() {
return 'GEMINI_API_KEY';
}
isRequiredApiKey() {
return false;
}
}
```
--------------------------------------------------------------------------------
/tests/integration/move-task-cross-tag.integration.test.js:
--------------------------------------------------------------------------------
```javascript
import { jest } from '@jest/globals';
import fs from 'fs';
import path from 'path';
import { fileURLToPath } from 'url';
const __filename = fileURLToPath(import.meta.url);
const __dirname = path.dirname(__filename);
// Mock dependencies before importing
const mockUtils = {
readJSON: jest.fn(),
writeJSON: jest.fn(),
findProjectRoot: jest.fn(() => '/test/project/root'),
log: jest.fn(),
setTasksForTag: jest.fn(),
traverseDependencies: jest.fn((sourceTasks, allTasks, options = {}) => {
// Mock realistic dependency behavior for testing
const { direction = 'forward' } = options;
if (direction === 'forward') {
// Return dependencies that tasks have
const result = [];
sourceTasks.forEach((task) => {
if (task.dependencies && Array.isArray(task.dependencies)) {
result.push(...task.dependencies);
}
});
return result;
} else if (direction === 'reverse') {
// Return tasks that depend on the source tasks
const sourceIds = sourceTasks.map((t) => t.id);
const normalizedSourceIds = sourceIds.map((id) => String(id));
const result = [];
allTasks.forEach((task) => {
if (task.dependencies && Array.isArray(task.dependencies)) {
const hasDependency = task.dependencies.some((depId) =>
normalizedSourceIds.includes(String(depId))
);
if (hasDependency) {
result.push(task.id);
}
}
});
return result;
}
return [];
})
};
// Mock the utils module
jest.unstable_mockModule('../../scripts/modules/utils.js', () => mockUtils);
// Mock other dependencies
jest.unstable_mockModule(
'../../scripts/modules/task-manager/is-task-dependent.js',
() => ({
default: jest.fn(() => false)
})
);
jest.unstable_mockModule('../../scripts/modules/dependency-manager.js', () => ({
findCrossTagDependencies: jest.fn(() => {
// Since dependencies can only exist within the same tag,
// this function should never find any cross-tag conflicts
return [];
}),
getDependentTaskIds: jest.fn(
(sourceTasks, crossTagDependencies, allTasks) => {
// Since we now use findAllDependenciesRecursively in the actual implementation,
// this mock simulates finding all dependencies recursively within the same tag
const dependentIds = new Set();
const processedIds = new Set();
function findAllDependencies(taskId) {
if (processedIds.has(taskId)) return;
processedIds.add(taskId);
const task = allTasks.find((t) => t.id === taskId);
if (!task || !Array.isArray(task.dependencies)) return;
task.dependencies.forEach((depId) => {
const normalizedDepId =
typeof depId === 'string' ? parseInt(depId, 10) : depId;
if (!isNaN(normalizedDepId) && normalizedDepId !== taskId) {
dependentIds.add(normalizedDepId);
findAllDependencies(normalizedDepId);
}
});
}
sourceTasks.forEach((sourceTask) => {
if (sourceTask && sourceTask.id) {
findAllDependencies(sourceTask.id);
}
});
return Array.from(dependentIds);
}
),
validateSubtaskMove: jest.fn((taskId, sourceTag, targetTag) => {
// Throw error for subtask IDs
const taskIdStr = String(taskId);
if (taskIdStr.includes('.')) {
throw new Error('Cannot move subtasks directly between tags');
}
})
}));
jest.unstable_mockModule(
'../../scripts/modules/task-manager/generate-task-files.js',
() => ({
default: jest.fn().mockResolvedValue()
})
);
// Import the modules we'll be testing after mocking
const { moveTasksBetweenTags } = await import(
'../../scripts/modules/task-manager/move-task.js'
);
describe('Cross-Tag Task Movement Integration Tests', () => {
let testDataPath;
let mockTasksData;
beforeEach(() => {
// Setup test data path
testDataPath = path.join(__dirname, 'temp-test-tasks.json');
// Initialize mock data with multiple tags
mockTasksData = {
backlog: {
tasks: [
{
id: 1,
title: 'Backlog Task 1',
description: 'A task in backlog',
status: 'pending',
dependencies: [],
priority: 'medium',
tag: 'backlog'
},
{
id: 2,
title: 'Backlog Task 2',
description: 'Another task in backlog',
status: 'pending',
dependencies: [1],
priority: 'high',
tag: 'backlog'
},
{
id: 3,
title: 'Backlog Task 3',
description: 'Independent task',
status: 'pending',
dependencies: [],
priority: 'low',
tag: 'backlog'
}
]
},
'in-progress': {
tasks: [
{
id: 4,
title: 'In Progress Task 1',
description: 'A task being worked on',
status: 'in-progress',
dependencies: [],
priority: 'high',
tag: 'in-progress'
}
]
},
done: {
tasks: [
{
id: 5,
title: 'Completed Task 1',
description: 'A completed task',
status: 'done',
dependencies: [],
priority: 'medium',
tag: 'done'
}
]
}
};
// Setup mock utils
mockUtils.readJSON.mockReturnValue(mockTasksData);
mockUtils.writeJSON.mockImplementation((path, data, projectRoot, tag) => {
// Simulate writing to file
return Promise.resolve();
});
});
afterEach(() => {
jest.clearAllMocks();
// Clean up temp file if it exists
if (fs.existsSync(testDataPath)) {
fs.unlinkSync(testDataPath);
}
});
describe('Basic Cross-Tag Movement', () => {
it('should move a single task between tags successfully', async () => {
const taskIds = [1];
const sourceTag = 'backlog';
const targetTag = 'in-progress';
const result = await moveTasksBetweenTags(
testDataPath,
taskIds,
sourceTag,
targetTag,
{},
{ projectRoot: '/test/project' }
);
// Verify readJSON was called with correct parameters
expect(mockUtils.readJSON).toHaveBeenCalledWith(
testDataPath,
'/test/project',
sourceTag
);
// Verify writeJSON was called with updated data
expect(mockUtils.writeJSON).toHaveBeenCalledWith(
testDataPath,
expect.objectContaining({
backlog: expect.objectContaining({
tasks: expect.arrayContaining([
expect.objectContaining({ id: 2 }),
expect.objectContaining({ id: 3 })
])
}),
'in-progress': expect.objectContaining({
tasks: expect.arrayContaining([
expect.objectContaining({ id: 4 }),
expect.objectContaining({
id: 1,
tag: 'in-progress'
})
])
})
}),
'/test/project',
null
);
// Verify result structure
expect(result).toEqual({
message: 'Successfully moved 1 tasks from "backlog" to "in-progress"',
movedTasks: [
{
id: 1,
fromTag: 'backlog',
toTag: 'in-progress'
}
]
});
});
it('should move multiple tasks between tags', async () => {
const taskIds = [1, 3];
const sourceTag = 'backlog';
const targetTag = 'done';
const result = await moveTasksBetweenTags(
testDataPath,
taskIds,
sourceTag,
targetTag,
{},
{ projectRoot: '/test/project' }
);
// Verify the moved tasks are in the target tag
expect(mockUtils.writeJSON).toHaveBeenCalledWith(
testDataPath,
expect.objectContaining({
backlog: expect.objectContaining({
tasks: expect.arrayContaining([expect.objectContaining({ id: 2 })])
}),
done: expect.objectContaining({
tasks: expect.arrayContaining([
expect.objectContaining({ id: 5 }),
expect.objectContaining({
id: 1,
tag: 'done'
}),
expect.objectContaining({
id: 3,
tag: 'done'
})
])
})
}),
'/test/project',
null
);
// Verify result structure
expect(result.movedTasks).toHaveLength(2);
expect(result.movedTasks).toEqual(
expect.arrayContaining([
{ id: 1, fromTag: 'backlog', toTag: 'done' },
{ id: 3, fromTag: 'backlog', toTag: 'done' }
])
);
});
it('should create target tag if it does not exist', async () => {
const taskIds = [1];
const sourceTag = 'backlog';
const targetTag = 'new-tag';
const result = await moveTasksBetweenTags(
testDataPath,
taskIds,
sourceTag,
targetTag,
{},
{ projectRoot: '/test/project' }
);
// Verify new tag was created
expect(mockUtils.writeJSON).toHaveBeenCalledWith(
testDataPath,
expect.objectContaining({
'new-tag': expect.objectContaining({
tasks: expect.arrayContaining([
expect.objectContaining({
id: 1,
tag: 'new-tag'
})
])
})
}),
'/test/project',
null
);
});
});
describe('Dependency Handling', () => {
it('should move task with dependencies when withDependencies is true', async () => {
const taskIds = [2]; // Task 2 depends on Task 1
const sourceTag = 'backlog';
const targetTag = 'in-progress';
const result = await moveTasksBetweenTags(
testDataPath,
taskIds,
sourceTag,
targetTag,
{ withDependencies: true },
{ projectRoot: '/test/project' }
);
// Verify both task 2 and its dependency (task 1) were moved
expect(mockUtils.writeJSON).toHaveBeenCalledWith(
testDataPath,
expect.objectContaining({
backlog: expect.objectContaining({
tasks: expect.arrayContaining([expect.objectContaining({ id: 3 })])
}),
'in-progress': expect.objectContaining({
tasks: expect.arrayContaining([
expect.objectContaining({ id: 4 }),
expect.objectContaining({
id: 1,
tag: 'in-progress'
}),
expect.objectContaining({
id: 2,
tag: 'in-progress'
})
])
})
}),
'/test/project',
null
);
});
it('should move task normally when ignoreDependencies is true (no cross-tag conflicts to ignore)', async () => {
const taskIds = [2]; // Task 2 depends on Task 1
const sourceTag = 'backlog';
const targetTag = 'in-progress';
const result = await moveTasksBetweenTags(
testDataPath,
taskIds,
sourceTag,
targetTag,
{ ignoreDependencies: true },
{ projectRoot: '/test/project' }
);
// Since dependencies only exist within tags, there are no cross-tag conflicts to ignore
// Task 2 moves with its dependencies intact
expect(mockUtils.writeJSON).toHaveBeenCalledWith(
testDataPath,
expect.objectContaining({
backlog: expect.objectContaining({
tasks: expect.arrayContaining([
expect.objectContaining({ id: 1 }),
expect.objectContaining({ id: 3 })
])
}),
'in-progress': expect.objectContaining({
tasks: expect.arrayContaining([
expect.objectContaining({ id: 4 }),
expect.objectContaining({
id: 2,
tag: 'in-progress',
dependencies: [1] // Dependencies preserved since no cross-tag conflicts
})
])
})
}),
'/test/project',
null
);
});
it('should provide advisory tips when ignoreDependencies breaks deps', async () => {
// Move a task that has dependencies so cross-tag conflicts would be broken
const taskIds = [2]; // backlog:2 depends on 1
const sourceTag = 'backlog';
const targetTag = 'in-progress';
// Override cross-tag detection to simulate conflicts for this case
const depManager = await import(
'../../scripts/modules/dependency-manager.js'
);
depManager.findCrossTagDependencies.mockReturnValueOnce([
{ taskId: 2, dependencyId: 1, dependencyTag: sourceTag }
]);
const result = await moveTasksBetweenTags(
testDataPath,
taskIds,
sourceTag,
targetTag,
{ ignoreDependencies: true },
{ projectRoot: '/test/project' }
);
expect(Array.isArray(result.tips)).toBe(true);
const expectedTips = [
'Run "task-master validate-dependencies" to check for dependency issues.',
'Run "task-master fix-dependencies" to automatically repair dangling dependencies.'
];
expect(result.tips).toHaveLength(expectedTips.length);
expect(result.tips).toEqual(expect.arrayContaining(expectedTips));
});
it('should move task without cross-tag dependency conflicts (since dependencies only exist within tags)', async () => {
const taskIds = [2]; // Task 2 depends on Task 1 (both in same tag)
const sourceTag = 'backlog';
const targetTag = 'in-progress';
// Since dependencies can only exist within the same tag,
// there should be no cross-tag conflicts
const result = await moveTasksBetweenTags(
testDataPath,
taskIds,
sourceTag,
targetTag,
{},
{ projectRoot: '/test/project' }
);
// Verify task was moved successfully (without dependencies)
expect(mockUtils.writeJSON).toHaveBeenCalledWith(
testDataPath,
expect.objectContaining({
backlog: expect.objectContaining({
tasks: expect.arrayContaining([
expect.objectContaining({ id: 1 }), // Task 1 stays in backlog
expect.objectContaining({ id: 3 })
])
}),
'in-progress': expect.objectContaining({
tasks: expect.arrayContaining([
expect.objectContaining({ id: 4 }),
expect.objectContaining({
id: 2,
tag: 'in-progress'
})
])
})
}),
'/test/project',
null
);
});
});
describe('Error Handling', () => {
it('should throw error for invalid source tag', async () => {
const taskIds = [1];
const sourceTag = 'nonexistent-tag';
const targetTag = 'in-progress';
// Mock readJSON to return data without the source tag
mockUtils.readJSON.mockReturnValue({
'in-progress': { tasks: [] }
});
await expect(
moveTasksBetweenTags(
testDataPath,
taskIds,
sourceTag,
targetTag,
{},
{ projectRoot: '/test/project' }
)
).rejects.toThrow('Source tag "nonexistent-tag" not found or invalid');
});
it('should throw error for invalid task IDs', async () => {
const taskIds = [999]; // Non-existent task ID
const sourceTag = 'backlog';
const targetTag = 'in-progress';
await expect(
moveTasksBetweenTags(
testDataPath,
taskIds,
sourceTag,
targetTag,
{},
{ projectRoot: '/test/project' }
)
).rejects.toThrow('Task 999 not found in source tag "backlog"');
});
it('should throw error for subtask movement', async () => {
const taskIds = ['1.1']; // Subtask ID
const sourceTag = 'backlog';
const targetTag = 'in-progress';
await expect(
moveTasksBetweenTags(
testDataPath,
taskIds,
sourceTag,
targetTag,
{},
{ projectRoot: '/test/project' }
)
).rejects.toThrow('Cannot move subtasks directly between tags');
});
it('should handle ID conflicts in target tag', async () => {
// Setup data with conflicting IDs
const conflictingData = {
backlog: {
tasks: [
{
id: 1,
title: 'Backlog Task',
tag: 'backlog'
}
]
},
'in-progress': {
tasks: [
{
id: 1, // Same ID as in backlog
title: 'In Progress Task',
tag: 'in-progress'
}
]
}
};
mockUtils.readJSON.mockReturnValue(conflictingData);
const taskIds = [1];
const sourceTag = 'backlog';
const targetTag = 'in-progress';
await expect(
moveTasksBetweenTags(
testDataPath,
taskIds,
sourceTag,
targetTag,
{},
{ projectRoot: '/test/project' }
)
).rejects.toThrow('Task 1 already exists in target tag "in-progress"');
// Validate suggestions on the error payload
try {
await moveTasksBetweenTags(
testDataPath,
taskIds,
sourceTag,
targetTag,
{},
{ projectRoot: '/test/project' }
);
} catch (err) {
expect(err.code).toBe('TASK_ALREADY_EXISTS');
expect(Array.isArray(err.data?.suggestions)).toBe(true);
const s = (err.data?.suggestions || []).join(' ');
expect(s).toContain('different target tag');
expect(s).toContain('different set of IDs');
expect(s).toContain('within-tag');
}
});
});
describe('Edge Cases', () => {
it('should handle empty task list in source tag', async () => {
const emptyData = {
backlog: { tasks: [] },
'in-progress': { tasks: [] }
};
mockUtils.readJSON.mockReturnValue(emptyData);
const taskIds = [1];
const sourceTag = 'backlog';
const targetTag = 'in-progress';
await expect(
moveTasksBetweenTags(
testDataPath,
taskIds,
sourceTag,
targetTag,
{},
{ projectRoot: '/test/project' }
)
).rejects.toThrow('Task 1 not found in source tag "backlog"');
});
it('should preserve task metadata during move', async () => {
const taskIds = [1];
const sourceTag = 'backlog';
const targetTag = 'in-progress';
const result = await moveTasksBetweenTags(
testDataPath,
taskIds,
sourceTag,
targetTag,
{},
{ projectRoot: '/test/project' }
);
// Verify task metadata is preserved
expect(mockUtils.writeJSON).toHaveBeenCalledWith(
testDataPath,
expect.objectContaining({
'in-progress': expect.objectContaining({
tasks: expect.arrayContaining([
expect.objectContaining({
id: 1,
title: 'Backlog Task 1',
description: 'A task in backlog',
status: 'pending',
priority: 'medium',
tag: 'in-progress', // Tag should be updated
metadata: expect.objectContaining({
moveHistory: expect.arrayContaining([
expect.objectContaining({
fromTag: 'backlog',
toTag: 'in-progress',
timestamp: expect.any(String)
})
])
})
})
])
})
}),
'/test/project',
null
);
});
// Note: force flag deprecated for cross-tag moves; covered by with/ignore dependencies tests
});
describe('Complex Scenarios', () => {
it('should handle complex moves without cross-tag conflicts (dependencies only within tags)', async () => {
// Setup data with valid within-tag dependencies
const validData = {
backlog: {
tasks: [
{
id: 1,
title: 'Task 1',
dependencies: [], // No dependencies
tag: 'backlog'
},
{
id: 3,
title: 'Task 3',
dependencies: [1], // Depends on Task 1 (same tag)
tag: 'backlog'
}
]
},
'in-progress': {
tasks: [
{
id: 2,
title: 'Task 2',
dependencies: [], // No dependencies
tag: 'in-progress'
}
]
}
};
mockUtils.readJSON.mockReturnValue(validData);
const taskIds = [3];
const sourceTag = 'backlog';
const targetTag = 'in-progress';
// Should succeed since there are no cross-tag conflicts
const result = await moveTasksBetweenTags(
testDataPath,
taskIds,
sourceTag,
targetTag,
{},
{ projectRoot: '/test/project' }
);
expect(result).toEqual({
message: 'Successfully moved 1 tasks from "backlog" to "in-progress"',
movedTasks: [{ id: 3, fromTag: 'backlog', toTag: 'in-progress' }]
});
});
it('should handle bulk move with mixed dependency scenarios', async () => {
const taskIds = [1, 2, 3]; // Multiple tasks with dependencies
const sourceTag = 'backlog';
const targetTag = 'in-progress';
const result = await moveTasksBetweenTags(
testDataPath,
taskIds,
sourceTag,
targetTag,
{ withDependencies: true },
{ projectRoot: '/test/project' }
);
// Verify all tasks were moved
expect(mockUtils.writeJSON).toHaveBeenCalledWith(
testDataPath,
expect.objectContaining({
backlog: expect.objectContaining({
tasks: [] // All tasks should be moved
}),
'in-progress': expect.objectContaining({
tasks: expect.arrayContaining([
expect.objectContaining({ id: 4 }),
expect.objectContaining({ id: 1, tag: 'in-progress' }),
expect.objectContaining({ id: 2, tag: 'in-progress' }),
expect.objectContaining({ id: 3, tag: 'in-progress' })
])
})
}),
'/test/project',
null
);
// Verify result structure
expect(result.movedTasks).toHaveLength(3);
expect(result.movedTasks).toEqual(
expect.arrayContaining([
{ id: 1, fromTag: 'backlog', toTag: 'in-progress' },
{ id: 2, fromTag: 'backlog', toTag: 'in-progress' },
{ id: 3, fromTag: 'backlog', toTag: 'in-progress' }
])
);
});
});
});
```