From 3b5a67e0e1f56c0b3b34946bcfe2d5c581803b23 Mon Sep 17 00:00:00 2001 From: Charles Lyding <19598772+clydin@users.noreply.github.com> Date: Mon, 18 May 2026 13:16:14 -0400 Subject: [PATCH] refactor(@angular/cli): implement experimental unified run_target facade and strategy dispatcher Introduce the unified `run_target` MCP tool and the underlying builder strategy dispatcher in a dedicated `tools/run-target` subdirectory. This architecture leverages the strategy pattern to delegate Angular CLI target executions (build, test, lint, e2e) to specialized internal strategies, defaulting to a universal `GenericTargetStrategy` fallback. --- .../cli/src/commands/mcp/mcp-server.ts | 9 +- .../run-target/generic-target-strategy.ts | 76 ++++++++++ .../mcp/tools/run-target/run-target.ts | 70 +++++++++ .../mcp/tools/run-target/run-target_spec.ts | 139 ++++++++++++++++++ .../commands/mcp/tools/run-target/strategy.ts | 18 +++ .../commands/mcp/tools/run-target/types.ts | 55 +++++++ 6 files changed, 366 insertions(+), 1 deletion(-) create mode 100644 packages/angular/cli/src/commands/mcp/tools/run-target/generic-target-strategy.ts create mode 100644 packages/angular/cli/src/commands/mcp/tools/run-target/run-target.ts create mode 100644 packages/angular/cli/src/commands/mcp/tools/run-target/run-target_spec.ts create mode 100644 packages/angular/cli/src/commands/mcp/tools/run-target/strategy.ts create mode 100644 packages/angular/cli/src/commands/mcp/tools/run-target/types.ts diff --git a/packages/angular/cli/src/commands/mcp/mcp-server.ts b/packages/angular/cli/src/commands/mcp/mcp-server.ts index 235ccf682372..eb08e36cdee7 100644 --- a/packages/angular/cli/src/commands/mcp/mcp-server.ts +++ b/packages/angular/cli/src/commands/mcp/mcp-server.ts @@ -25,6 +25,7 @@ import { DOC_SEARCH_TOOL } from './tools/doc-search'; import { E2E_TOOL } from './tools/e2e'; import { ZONELESS_MIGRATION_TOOL } from './tools/onpush-zoneless-migration/zoneless-migration'; import { LIST_PROJECTS_TOOL } from './tools/projects'; +import { RUN_TARGET_TOOL } from './tools/run-target/run-target'; import { TEST_TOOL } from './tools/test'; import { type AnyMcpToolDeclaration, registerTools } from './tools/tool-registry'; @@ -49,7 +50,13 @@ const STABLE_TOOLS = [ * The set of tools that are available but not enabled by default. * These tools are considered experimental and may have limitations. */ -export const EXPERIMENTAL_TOOLS = [BUILD_TOOL, E2E_TOOL, TEST_TOOL, ...DEVSERVER_TOOLS] as const; +export const EXPERIMENTAL_TOOLS = [ + BUILD_TOOL, + E2E_TOOL, + TEST_TOOL, + RUN_TARGET_TOOL, + ...DEVSERVER_TOOLS, +] as const; /** * Experimental tools that are grouped together under a single name. diff --git a/packages/angular/cli/src/commands/mcp/tools/run-target/generic-target-strategy.ts b/packages/angular/cli/src/commands/mcp/tools/run-target/generic-target-strategy.ts new file mode 100644 index 000000000000..a93824f5d6c3 --- /dev/null +++ b/packages/angular/cli/src/commands/mcp/tools/run-target/generic-target-strategy.ts @@ -0,0 +1,76 @@ +/** + * @license + * Copyright Google LLC All Rights Reserved. + * + * Use of this source code is governed by an MIT-style license that can be + * found in the LICENSE file at https://angular.dev/license + */ + +import { getCommandErrorLogs } from '../../utils'; +import type { McpToolContext } from '../tool-registry'; +import type { TargetStrategy } from './strategy'; +import type { RunTargetOutput, StrategyExecutionContext } from './types'; + +export class GenericTargetStrategy implements TargetStrategy { + canHandle(target: string, builder?: string): boolean { + return true; // Universal fallback strategy + } + + async execute( + input: StrategyExecutionContext, + context: McpToolContext, + ): Promise { + if (input.target === 'serve' || input.options?.['watch'] === true) { + throw new Error( + `Watch mode execution (serve target or watch option) is not yet supported by 'run_target'. ` + + `Please use the legacy 'devserver.start' / 'devserver.wait_for_build' tools instead.`, + ); + } + + const args = [input.target, input.projectName]; + if (input.configuration) { + args.push('-c', input.configuration); + } + + let options = input.options; + if (input.target === 'test') { + options = { + ...options, + watch: false, + }; + } + + if (options) { + for (const [key, value] of Object.entries(options)) { + if (!/^[a-zA-Z0-9-_]+$/.test(key)) { + throw new Error( + `Invalid option key: '${key}'. Option keys must be alphanumeric, hyphens, or underscores.`, + ); + } + + if (typeof value === 'boolean') { + args.push(value ? `--${key}` : `--no-${key}`); + } else if (Array.isArray(value)) { + for (const item of value) { + args.push(`--${key}=${item}`); + } + } else if (value !== null && value !== undefined) { + args.push(`--${key}=${value}`); + } + } + } + + let status: 'success' | 'failure' = 'success'; + let logs: string[]; + + try { + const result = await context.host.executeNgCommand(args, { cwd: input.workspacePath }); + logs = result.logs; + } catch (e) { + status = 'failure'; + logs = getCommandErrorLogs(e); + } + + return { status, logs }; + } +} diff --git a/packages/angular/cli/src/commands/mcp/tools/run-target/run-target.ts b/packages/angular/cli/src/commands/mcp/tools/run-target/run-target.ts new file mode 100644 index 000000000000..0dacdaecb209 --- /dev/null +++ b/packages/angular/cli/src/commands/mcp/tools/run-target/run-target.ts @@ -0,0 +1,70 @@ +/** + * @license + * Copyright Google LLC All Rights Reserved. + * + * Use of this source code is governed by an MIT-style license that can be + * found in the LICENSE file at https://angular.dev/license + */ + +import { createStructuredContentOutput } from '../../utils'; +import { resolveWorkspaceAndProject } from '../../workspace-utils'; +import { type McpToolContext, declareTool } from '../tool-registry'; +import { GenericTargetStrategy } from './generic-target-strategy'; +import type { TargetStrategy } from './strategy'; +import { type RunTargetInput, runTargetInputSchema, runTargetOutputSchema } from './types'; + +const FALLBACK_STRATEGY = new GenericTargetStrategy(); +const STRATEGIES: TargetStrategy[] = []; + +export async function runTarget(input: RunTargetInput, context: McpToolContext) { + const { workspace, workspacePath, projectName } = await resolveWorkspaceAndProject({ + host: context.host, + server: context.server, + workspacePathInput: input.workspace, + projectNameInput: input.project, + mcpWorkspace: context.workspace, + }); + + const targetDefinition = workspace.projects.get(projectName)?.targets.get(input.target); + const builder = targetDefinition?.builder; + + const strategy = STRATEGIES.find((s) => s.canHandle(input.target, builder)) ?? FALLBACK_STRATEGY; + + const result = await strategy.execute( + { + workspacePath, + projectName, + target: input.target, + configuration: input.configuration, + options: input.options, + }, + context, + ); + + return createStructuredContentOutput(result); +} + +export const RUN_TARGET_TOOL = declareTool({ + name: 'run_target', + title: 'Run Project Target', + description: ` + +Executes a configured target (such as build, test, lint, e2e) for an Angular project. +This is the single, unified interface for executing all project tasks natively. + + +* Building an application or library. +* Running unit tests, E2E tests, or linters. +* Deploying or running custom workspace targets discovered via 'list_projects'. + + +* Mandatory Discovery: You MUST discover available project targets by calling 'list_projects' first. +* Watch mode (serve target or watch options) is NOT yet supported in this version of run_target. + You MUST use the legacy 'devserver.*' tools for background server lifecycles. +`, + isReadOnly: false, + isLocalOnly: true, + inputSchema: runTargetInputSchema.shape, + outputSchema: runTargetOutputSchema.shape, + factory: (context) => (input) => runTarget(input, context), +}); diff --git a/packages/angular/cli/src/commands/mcp/tools/run-target/run-target_spec.ts b/packages/angular/cli/src/commands/mcp/tools/run-target/run-target_spec.ts new file mode 100644 index 000000000000..5aefc893fc16 --- /dev/null +++ b/packages/angular/cli/src/commands/mcp/tools/run-target/run-target_spec.ts @@ -0,0 +1,139 @@ +/** + * @license + * Copyright Google LLC All Rights Reserved. + * + * Use of this source code is governed by an MIT-style license that can be + * found in the LICENSE file at https://angular.dev/license + */ + +import { CommandError } from '../../host'; +import type { MockHost } from '../../testing/mock-host'; +import { + type MockMcpToolContext, + addProjectToWorkspace, + createMockContext, +} from '../../testing/test-utils'; +import { runTarget } from './run-target'; + +describe('Run Target Tool', () => { + let mockHost: MockHost; + let mockContext: MockMcpToolContext; + + beforeEach(() => { + const mock = createMockContext(); + mockHost = mock.host; + mockContext = mock.context; + addProjectToWorkspace(mock.projects, 'my-app'); + }); + + it('should construct the command correctly with target and default project', async () => { + mockContext.workspace.extensions['defaultProject'] = 'my-app'; + await runTarget({ target: 'build' }, mockContext); + expect(mockHost.executeNgCommand).toHaveBeenCalledWith(['build', 'my-app'], { cwd: '/test' }); + }); + + it('should construct the command correctly with a specified project', async () => { + addProjectToWorkspace(mockContext.workspace.projects, 'my-lib'); + await runTarget({ project: 'my-lib', target: 'lint' }, mockContext); + expect(mockHost.executeNgCommand).toHaveBeenCalledWith(['lint', 'my-lib'], { cwd: '/test' }); + }); + + it('should construct the command correctly with configuration', async () => { + mockContext.workspace.extensions['defaultProject'] = 'my-app'; + await runTarget({ target: 'build', configuration: 'production' }, mockContext); + expect(mockHost.executeNgCommand).toHaveBeenCalledWith( + ['build', 'my-app', '-c', 'production'], + { + cwd: '/test', + }, + ); + }); + + it('should map boolean options correctly to CLI flags', async () => { + mockContext.workspace.extensions['defaultProject'] = 'my-app'; + await runTarget({ target: 'lint', options: { fix: true, quiet: false } }, mockContext); + expect(mockHost.executeNgCommand).toHaveBeenCalledWith( + ['lint', 'my-app', '--fix', '--no-quiet'], + { cwd: '/test' }, + ); + }); + + it('should map string and number options correctly to CLI flags and auto-inject no-watch', async () => { + mockContext.workspace.extensions['defaultProject'] = 'my-app'; + await runTarget( + { target: 'test', options: { browsers: 'ChromeHeadless', timeout: 5000 } }, + mockContext, + ); + expect(mockHost.executeNgCommand).toHaveBeenCalledWith( + ['test', 'my-app', '--browsers=ChromeHeadless', '--timeout=5000', '--no-watch'], + { cwd: '/test' }, + ); + }); + + it('should map array options correctly as multiple occurrences of the flag', async () => { + mockContext.workspace.extensions['defaultProject'] = 'my-app'; + await runTarget({ target: 'lint', options: { include: ['a', 'b'] } }, mockContext); + expect(mockHost.executeNgCommand).toHaveBeenCalledWith( + ['lint', 'my-app', '--include=a', '--include=b'], + { cwd: '/test' }, + ); + }); + + it('should automatically inject no-watch for test target even if no options provided', async () => { + mockContext.workspace.extensions['defaultProject'] = 'my-app'; + await runTarget({ target: 'test' }, mockContext); + expect(mockHost.executeNgCommand).toHaveBeenCalledWith(['test', 'my-app', '--no-watch'], { + cwd: '/test', + }); + }); + + it('should throw an error if option key is malformed (contains whitespace/special chars)', async () => { + mockContext.workspace.extensions['defaultProject'] = 'my-app'; + await expectAsync( + runTarget({ target: 'lint', options: { 'fix --danger': true } }, mockContext), + ).toBeRejectedWithError(/Invalid option key: 'fix --danger'/); + }); + + it('should handle a successful execution and return logs', async () => { + const executionLogs = ['Linting complete', 'All rules passed!']; + mockHost.executeNgCommand.and.resolveTo({ + logs: executionLogs, + }); + + const { structuredContent } = await runTarget( + { project: 'my-app', target: 'lint' }, + mockContext, + ); + + expect(structuredContent.status).toBe('success'); + expect(structuredContent.logs).toEqual(executionLogs); + }); + + it('should handle a failed execution and capture command errors', async () => { + const executionLogs = ['Error: Rule violation found.']; + const error = new CommandError('Lint failed', executionLogs, 1); + mockHost.executeNgCommand.and.rejectWith(error); + + const { structuredContent } = await runTarget( + { project: 'my-app', target: 'lint' }, + mockContext, + ); + + expect(structuredContent.status).toBe('failure'); + expect(structuredContent.logs).toEqual([...executionLogs, 'Lint failed']); + }); + + it('should throw an error if attempting to run the serve target', async () => { + mockContext.workspace.extensions['defaultProject'] = 'my-app'; + await expectAsync(runTarget({ target: 'serve' }, mockContext)).toBeRejectedWithError( + /Watch mode execution.*is not yet supported/, + ); + }); + + it('should throw an error if attempting to run a target with watch option true', async () => { + mockContext.workspace.extensions['defaultProject'] = 'my-app'; + await expectAsync( + runTarget({ target: 'build', options: { watch: true } }, mockContext), + ).toBeRejectedWithError(/Watch mode execution.*is not yet supported/); + }); +}); diff --git a/packages/angular/cli/src/commands/mcp/tools/run-target/strategy.ts b/packages/angular/cli/src/commands/mcp/tools/run-target/strategy.ts new file mode 100644 index 000000000000..8c149a174f93 --- /dev/null +++ b/packages/angular/cli/src/commands/mcp/tools/run-target/strategy.ts @@ -0,0 +1,18 @@ +/** + * @license + * Copyright Google LLC All Rights Reserved. + * + * Use of this source code is governed by an MIT-style license that can be + * found in the LICENSE file at https://angular.dev/license + */ + +import type { McpToolContext } from '../tool-registry'; +import type { RunTargetOutput, StrategyExecutionContext } from './types'; + +export interface TargetStrategy { + /** Whether this strategy is responsible for handling the given target/builder */ + canHandle(target: string, builder?: string): boolean; + + /** Executes the target using this strategy */ + execute(input: StrategyExecutionContext, context: McpToolContext): Promise; +} diff --git a/packages/angular/cli/src/commands/mcp/tools/run-target/types.ts b/packages/angular/cli/src/commands/mcp/tools/run-target/types.ts new file mode 100644 index 000000000000..aa0d3a0cf7ca --- /dev/null +++ b/packages/angular/cli/src/commands/mcp/tools/run-target/types.ts @@ -0,0 +1,55 @@ +/** + * @license + * Copyright Google LLC All Rights Reserved. + * + * Use of this source code is governed by an MIT-style license that can be + * found in the LICENSE file at https://angular.dev/license + */ + +import { z } from 'zod'; +import { workspaceAndProjectOptions } from '../../shared-options'; + +export const optionValueSchema = z.union([ + z.string(), + z.number(), + z.boolean(), + z.array(z.union([z.string(), z.number()])), +]); + +export type OptionValue = z.infer; + +export const runTargetInputSchema = z.object({ + ...workspaceAndProjectOptions, + target: z + .string() + .describe('The project target to execute (e.g., "build", "test", "lint", "e2e", "deploy").'), + configuration: z + .string() + .optional() + .describe('Target configuration (e.g., "development", "production").'), + options: z + .record(z.string(), optionValueSchema) + .optional() + .describe('Optional key-value options to override the configured target options.'), +}); + +export type RunTargetInput = z.infer; + +export const runTargetOutputSchema = z.object({ + status: z.enum(['success', 'failure']).describe('Execution status.'), + logs: z.array(z.string()).describe('Clean, line-buffered output logs from execution.'), + extensions: z + .record(z.string(), z.unknown()) + .optional() + .describe('Specialized metadata populated by specific target strategies.'), +}); + +export type RunTargetOutput = z.infer; + +export interface StrategyExecutionContext { + workspacePath: string; + projectName: string; + target: string; + configuration?: string; + options?: Record; +}