Skip to content

Commit e0311ef

Browse files
codeaholicguycodeaholicguy
committed
feat(cli): migrate agent command to @ai-devkit/agent-manager
- switch agent command imports to package APIs and keep CLI display mapping local - remove duplicated CLI agent-manager source files and legacy tests - stabilize process utility tests to eliminate flaky cli:test behavior - add agent command tests and update docs/ai lifecycle artifacts for feature-agent-manager-package
1 parent 661ff87 commit e0311ef

18 files changed

+793
-1782
lines changed

‎docs/ai/design/feature-agent-manager-package.md‎

Lines changed: 96 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,96 @@
1+
---
2+
phase: design
3+
title: "CLI Agent-Manager Package Adoption - Design"
4+
feature: agent-manager-package
5+
description: Architecture and migration design for moving CLI agent logic to @ai-devkit/agent-manager
6+
---
7+
8+
# Design: CLI Adoption of @ai-devkit/agent-manager
9+
10+
## Architecture Overview
11+
12+
```mermaid
13+
graph TD
14+
User[User runs ai-devkit agent] --> Cmd[packages/cli/src/commands/agent.ts]
15+
16+
subgraph CLI
17+
Cmd --> UILayer[CLI formatting + table output + command errors]
18+
Cmd --> DisplayMap[Status/time display mapping]
19+
end
20+
21+
subgraph AgentManagerPkg[@ai-devkit/agent-manager]
22+
AM[AgentManager]
23+
CCA[ClaudeCodeAdapter]
24+
TFM[TerminalFocusManager]
25+
Types[AgentInfo/AgentStatus/AgentType]
26+
AM --> CCA
27+
CCA --> Types
28+
end
29+
30+
Cmd -->|imports| AM
31+
Cmd -->|imports| CCA
32+
Cmd -->|imports| TFM
33+
Cmd -->|imports| Types
34+
Cmd -->|uses| DisplayMap
35+
```
36+
37+
Responsibilities:
38+
- `@ai-devkit/agent-manager`: detection, adapter contract, status model, agent resolution, terminal focus mechanics
39+
- CLI: command wiring, display formatting, JSON/table output, user-facing errors, focus-flow orchestration only
40+
41+
## Data Models
42+
43+
Core models consumed from package:
44+
- `AgentInfo`
45+
- `AgentStatus`
46+
- `AgentType`
47+
- `TerminalFocusManager`
48+
- Adapter interface types as needed
49+
50+
CLI-owned view model:
51+
- Derived display fields (color/emoji labels, relative time strings, message formatting)
52+
- Local status metadata map for display labels/colors (replacing direct dependency on legacy CLI `STATUS_CONFIG`)
53+
54+
## API Design
55+
56+
### CLI Imports
57+
- Prefer root exports from `@ai-devkit/agent-manager`
58+
- Keep imports explicit and type-safe in `commands/agent.ts`
59+
60+
### Internal CLI Interface
61+
- Introduce minimal local mappers (if needed) for display-only transformations
62+
- Avoid re-defining package-level domain types in CLI
63+
64+
## Component Breakdown
65+
66+
1. `packages/cli/src/commands/agent.ts`
67+
- Replace local lib imports with package imports
68+
- Keep output behavior unchanged
69+
70+
2. CLI local cleanup
71+
- Remove duplicated files under `packages/cli/src/lib` and `packages/cli/src/__tests__/lib` that are fully migrated, including `lib/TerminalFocusManager.ts`
72+
- Use direct import replacement and delete duplicates in the same change set (no temporary compatibility wrappers)
73+
- Retain only files that are intentionally CLI-specific
74+
75+
3. Tests
76+
- Update tests to validate behavior through CLI command interfaces and remaining unit seams
77+
78+
## Design Decisions
79+
80+
- Decision: package is source of truth for agent detection and status domain model.
81+
- Rationale: eliminates duplication and drift.
82+
- Decision: package is also source of truth for terminal focus implementation (`TerminalFocusManager`).
83+
- Rationale: aligns with cleanup goal and removes final duplicated agent-manager file path in CLI.
84+
- Decision: CLI keeps presentation concerns.
85+
- Rationale: package remains reusable and data-first.
86+
- Decision: cleanup is included in the same feature.
87+
- Rationale: avoids leaving dead or competing implementations.
88+
- Decision: no lint-rule enforcement is added in this feature for import path policy.
89+
- Rationale: team prefers convention over additional tooling in this phase.
90+
91+
## Non-Functional Requirements
92+
93+
- Performance: no meaningful regression for `agent list` runtime
94+
- Reliability: migration must preserve existing command behavior and error handling
95+
- Maintainability: eliminate duplicate agent-manager code paths in CLI
96+
- Security: preserve existing process/file handling guarantees; do not widen command-execution surface

‎docs/ai/implementation/feature-agent-manager-package.md‎

Lines changed: 114 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,114 @@
1+
---
2+
phase: implementation
3+
title: "CLI Agent-Manager Package Adoption - Implementation Guide"
4+
feature: agent-manager-package
5+
description: Implementation notes for migrating CLI agent logic to @ai-devkit/agent-manager
6+
---
7+
8+
# Implementation Guide: CLI Uses @ai-devkit/agent-manager
9+
10+
## Development Setup
11+
12+
- Use repository root with npm workspaces enabled
13+
- Validate changes with project lint/build/test commands after migration
14+
15+
## Code Structure
16+
17+
- Primary touchpoint: `packages/cli/src/commands/agent.ts`
18+
- Candidate cleanup area: `packages/cli/src/lib/*agent*` and related `src/__tests__/lib/*agent*`
19+
- External dependency source: `packages/agent-manager/src/*`
20+
21+
## Implementation Notes
22+
23+
### Core Features
24+
- Replace local CLI domain imports with `@ai-devkit/agent-manager` imports
25+
- Keep CLI-only formatting and command UX logic local
26+
- Remove duplicate implementations once imports are migrated and verified
27+
28+
### Patterns & Best Practices
29+
- Keep domain logic in package, presentation logic in CLI
30+
- Prefer explicit imports over local re-export indirection
31+
- Delete dead code in same change set to prevent drift
32+
33+
## Integration Points
34+
35+
- CLI command integration with package classes/types
36+
- Workspace dependency metadata between `packages/cli` and `packages/agent-manager`
37+
38+
## Error Handling
39+
40+
- Preserve current user-facing errors/messages in `agent` command flows
41+
- Keep graceful handling for no-agent and lookup/focus failures
42+
43+
## Performance Considerations
44+
45+
- Avoid extra scans/parsing during migration
46+
- Maintain current command runtime profile
47+
48+
## Security Notes
49+
50+
- Reuse package utilities without introducing new shell-eval paths
51+
- Keep terminal focus behavior constrained to existing safe execution patterns
52+
53+
## Implementation Status (February 26, 2026)
54+
55+
- Migrated CLI agent command imports in `packages/cli/src/commands/agent.ts` to `@ai-devkit/agent-manager`:
56+
- `AgentManager`
57+
- `ClaudeCodeAdapter`
58+
- `AgentStatus`
59+
- `TerminalFocusManager`
60+
- `AgentInfo` (type)
61+
- Replaced removed legacy display fields with CLI-local presentation mapping:
62+
- status display (`run`, `wait`, `idle`, `unknown`)
63+
- relative time formatting for `lastActive`
64+
- Added workspace dependency in `packages/cli/package.json`:
65+
- `@ai-devkit/agent-manager: 0.1.0`
66+
- Updated shared CLI process utility type import:
67+
- `packages/cli/src/util/process.ts` now imports `ProcessInfo` from `@ai-devkit/agent-manager`
68+
- Removed duplicated CLI agent-manager source files:
69+
- `packages/cli/src/lib/AgentManager.ts`
70+
- `packages/cli/src/lib/TerminalFocusManager.ts`
71+
- `packages/cli/src/lib/adapters/AgentAdapter.ts`
72+
- `packages/cli/src/lib/adapters/ClaudeCodeAdapter.ts`
73+
- Removed duplicated CLI tests tied to deleted modules:
74+
- `packages/cli/src/__tests__/lib/AgentManager.test.ts`
75+
- `packages/cli/src/__tests__/lib/TerminalFocusManager.test.ts`
76+
- `packages/cli/src/__tests__/lib/adapters/ClaudeCodeAdapter.test.ts`
77+
78+
## Phase 6 Check Implementation (February 26, 2026)
79+
80+
### Alignment Summary
81+
82+
- Overall status: aligned with requirements and design
83+
- Package ownership migration completed for `AgentManager`, `ClaudeCodeAdapter`, core agent types/status, and `TerminalFocusManager`
84+
- CLI keeps presentation logic locally (status/time formatting, command UX, prompts, output)
85+
86+
### File-by-File Notes
87+
88+
- `packages/cli/src/commands/agent.ts`
89+
- Uses `@ai-devkit/agent-manager` imports as required
90+
- Replaces removed package-display fields with local formatter functions
91+
- `packages/cli/package.json`
92+
- Includes direct dependency on `@ai-devkit/agent-manager`
93+
- `packages/cli/src/util/process.ts`
94+
- Uses shared `ProcessInfo` type from package
95+
- Removed files under `packages/cli/src/lib/*agent*` and matching tests under `packages/cli/src/__tests__/lib/*agent*`
96+
- Matches direct-replacement/no-wrapper decision
97+
98+
### Deviations / Concerns
99+
100+
- No requirement/design deviations found.
101+
- Follow-up optimization (non-blocking): optional reduction of expected `console.error` noise in failure-path unit tests.
102+
103+
## Phase 8 Code Review (February 26, 2026)
104+
105+
### Findings
106+
107+
1. No blocking correctness, security, or design-alignment issues found in migrated CLI/package integration paths.
108+
2. Test coverage for changed command path improved via `packages/cli/src/__tests__/commands/agent.test.ts`, but package-level global coverage thresholds remain below 80% due unrelated historical coverage gaps.
109+
3. Non-blocking quality note: expected `console.error` output in negative-path tests can be muted with console spies if cleaner CI logs are preferred.
110+
111+
### Review Verdict
112+
113+
- Ready for commit/PR from a code-review standpoint.
114+
- Remaining items are non-blocking follow-up improvements, not release blockers for this feature scope.

‎docs/ai/planning/feature-agent-manager-package.md‎

Lines changed: 70 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,70 @@
1+
---
2+
phase: planning
3+
title: "CLI Agent-Manager Package Adoption - Planning"
4+
feature: agent-manager-package
5+
description: Task breakdown for migrating CLI to @ai-devkit/agent-manager and cleaning duplicated files
6+
---
7+
8+
# Planning: CLI Uses @ai-devkit/agent-manager
9+
10+
## Milestones
11+
12+
- [x] Milestone 1: CLI imports migrated to package
13+
- [x] Milestone 2: Duplicated CLI agent-manager files removed/retired
14+
- [x] Milestone 3: Tests and validation complete with no regressions
15+
16+
## Task Breakdown
17+
18+
### Phase 1: Foundation
19+
- [x] Task 1.1: Confirm package API used by CLI (`AgentManager`, `ClaudeCodeAdapter`, core types)
20+
- [x] Task 1.2: Add/update CLI dependency on `@ai-devkit/agent-manager` in workspace manifests
21+
- [x] Task 1.3: Update `packages/cli/src/commands/agent.ts` imports to package equivalents
22+
23+
### Phase 2: Migration & Cleanup
24+
- [x] Task 2.1: Replace any remaining direct references to duplicated CLI agent-management modules
25+
- [x] Task 2.2: Remove migrated files in `packages/cli/src/lib` and related tests under `src/__tests__/lib`
26+
- [x] Task 2.3: Keep or isolate CLI-specific terminal focus code based on final boundary decision
27+
28+
### Phase 3: Validation & Polish
29+
- [x] Task 3.1: Update tests to cover package-backed CLI behavior
30+
- [x] Task 3.2: Run lint/build/test for affected packages
31+
- [x] Task 3.3: Verify manual behavior for `agent list`, `agent list --json`, and `agent open`
32+
- [x] Task 3.4: Remove dead exports/imports and ensure clean TypeScript build
33+
34+
## Dependencies
35+
36+
- Task 1.1 must complete before Task 1.3
37+
- Task 1.3 must complete before file deletion in Task 2.2
38+
- Task 2.x tasks must complete before final validation in Task 3.x
39+
40+
## Timeline & Estimates
41+
42+
- Phase 1: 0.5 day
43+
- Phase 2: 0.5-1 day
44+
- Phase 3: 0.5 day
45+
- Total estimate: 1.5-2 days
46+
47+
## Risks & Mitigation
48+
49+
- Risk: package/CLI type mismatch blocks migration
50+
- Mitigation: add small CLI adapter/mapping layer for display-only transformations
51+
- Risk: cleanup removes code still used indirectly
52+
- Mitigation: use `rg` reference checks before deletion and run full TypeScript build
53+
- Risk: behavior regression in user-facing command output
54+
- Mitigation: run existing tests plus targeted manual verification of output paths
55+
56+
## Resources Needed
57+
58+
- Existing `feature-agent-manager` docs and package implementation
59+
- CLI command/test suite for `agent` commands
60+
- Local runtime with access to Node/npm and workspace scripts
61+
62+
## Progress Summary
63+
64+
Implementation scope is complete: CLI now consumes `@ai-devkit/agent-manager`, duplicated CLI agent-manager sources/tests were removed, and validation targets passed. Post-implementation stabilization addressed a flaky `cli:test` signal by making `process` utility tests deterministic via mocking instead of host-process introspection. No scope expansion was introduced; remaining work is lifecycle closure (implementation check, final testing/code review pass).
65+
66+
## Next Actionable Tasks
67+
68+
1. Run Phase 6 implementation check and document any deviations from requirements/design.
69+
2. Run Phase 7 test-phase documentation update with final stability notes.
70+
3. Run Phase 8 code review for final risk scan before commit/PR.

‎docs/ai/requirements/feature-agent-manager-package.md‎

Lines changed: 68 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,68 @@
1+
---
2+
phase: requirements
3+
title: "CLI Agent-Manager Package Adoption - Requirements"
4+
feature: agent-manager-package
5+
description: Make CLI consume @ai-devkit/agent-manager and remove duplicated agent-management code from CLI
6+
---
7+
8+
# Requirements: CLI Uses @ai-devkit/agent-manager
9+
10+
## Problem Statement
11+
12+
`packages/agent-manager` exists, but `packages/cli` still uses local agent-management implementations (`AgentManager`, Claude adapter, related types). This duplicates logic across packages and creates drift risk.
13+
14+
Who is affected:
15+
- CLI maintainers who must patch agent behavior in more than one place
16+
- Contributors who are unsure which implementation is source of truth
17+
- Users who can receive inconsistent behavior when package and CLI diverge
18+
19+
## Goals & Objectives
20+
21+
### Primary Goals
22+
- Switch `packages/cli` agent command(s) to import core agent-management logic from `@ai-devkit/agent-manager`
23+
- Remove or retire duplicated CLI agent-management files no longer needed
24+
- Migrate `TerminalFocusManager` usage to `@ai-devkit/agent-manager` and remove CLI duplicate
25+
- Keep current CLI command behavior and output stable for users
26+
27+
### Secondary Goals
28+
- Reduce maintenance surface in `packages/cli/src/lib`
29+
- Make ownership boundary explicit: domain logic in package, presentation in CLI
30+
- Keep test coverage equivalent or better after migration
31+
32+
### Non-Goals
33+
- Adding new agent types or features
34+
- Redesigning `ai-devkit agent` UX
35+
- Large refactors unrelated to agent-management duplication
36+
37+
## User Stories & Use Cases
38+
39+
1. As a CLI maintainer, I want one reusable agent-management implementation so fixes happen once.
40+
2. As a contributor, I want clear imports from `@ai-devkit/agent-manager` so package boundaries are obvious.
41+
3. As an end user, I want `ai-devkit agent list/open` to behave the same after migration.
42+
43+
## Success Criteria
44+
45+
- `packages/cli/src/commands/agent.ts` imports core types/classes from `@ai-devkit/agent-manager`
46+
- `packages/cli/src/commands/agent.ts` imports `TerminalFocusManager` from `@ai-devkit/agent-manager`
47+
- Duplicated CLI files for migrated functionality are removed or converted to thin wrappers
48+
- CLI tests pass with package-based imports
49+
- `npm run lint`, `npm run build`, and relevant tests pass for affected projects
50+
- No functional regression in `agent list`, `agent list --json`, and `agent open`
51+
52+
## Constraints & Assumptions
53+
54+
### Technical Constraints
55+
- Follow existing Nx/workspace conventions
56+
- Preserve Node.js compatibility declared in repo
57+
- Keep output formatting responsibility in CLI layer
58+
59+
### Assumptions
60+
- `@ai-devkit/agent-manager` API is stable enough for CLI adoption
61+
- `TerminalFocusManager` in `@ai-devkit/agent-manager` is the source for CLI terminal focus behavior
62+
- Existing tests can be updated without changing command semantics
63+
64+
## Questions & Open Items
65+
66+
- Resolved: Consume `TerminalFocusManager` from `@ai-devkit/agent-manager` in this phase and remove `packages/cli/src/lib/TerminalFocusManager.ts`.
67+
- Resolved: Use direct import replacement and remove duplicated CLI agent-manager files in the same change (no compatibility wrapper period).
68+
- Resolved: Do not add a lint rule for import enforcement in this feature; keep as team convention.

0 commit comments

Comments
 (0)